rustial_engine/map_state/

mod.rs

// ---------------------------------------------------------------------------
//! # Map state -- the central per-frame state object
//!
//! [`MapState`] owns every piece of data the engine needs todescribe a
//! single frame of the map: camera, layers, terrain, animation, and
//! precomputed derived values (zoom level, viewport bounds, frustum).
//!
//! ## Lifecycle (host <-> engine <-> renderer)
//!
//! ```text
//!  Host application                    Engine (MapState)           Renderer
//!  +----------------+                  +--------------+           +----------+
//!  | winit / Bevy   |-- handle_input ->|              |           |          |
//!  | event loop     |-- fly_to ------->|  update()    |           |          |
//!  |                |                  |  update_     |           |          |
//!  |                |                  |  with_dt()   |           |          |
//!  |                |                  |              |           |          |
//!  |                |                  | frame_output +---------->| render() |
//!  +----------------+                  +--------------+           +----------+
//! ```
//!
//! 1. **Input** -- the host feeds [`InputEvent`]s via
//!    [`handle_input`](MapState::handle_input).
//! 2. **Update** -- the host calls [`update`](MapState::update) (or
//!    [`update_with_dt`](MapState::update_with_dt)) once per frame.
//!    This ticks the camera animator, recomputes the zoom level and
//!    viewport bounds, rebuilds terrain meshes, and iterates the layer
//!    stack to update tile, vector, and model data.
//! 3. **Read** -- the renderer reads derived state either through direct
//!    field access (`camera`, `vector_meshes`, `model_instances`) or
//!    through accessor methods (`visible_tiles()`, `terrain_meshes()`,
//!    `zoom_level()`).  Alternatively, call
//!    [`frame_output`](MapState::frame_output) to obtain a detached
//!    snapshot that can be sent to a render thread.
//!...                                                                   - `zoom_level` -- Current integer zoom level (0-22).
//!    - `viewport_bounds` -- Viewport bounding box in Web Mercator world space.
//!    - `scene_viewport_bounds` -- Viewport bounding box in the active planar scene projection.
//!    - `frustum` -- View frustum planes (derived from the camera VP matrix).
//!    - `terrain_meshes` -- Terrain meshes produced during this frame's `update()`.
//!    - `hillshade_rasters` -- Prepared hillshade rasters for the last `update()`.
//!    - `visible_tiles` -- Visible tiles produced by the tile layer (or set externally).
//! - **Per-frame layer output**:
//!    - `vector_meshes` -- Tessellated vector meshes from the last `update()`.
//!    - `model_instances` -- 3D model instances collected from all visible
//!      [`ModelLayer`](crate::layers::ModelLayer)s during the last `update()`.
//!    - `placed_symbols` -- Placed symbols after collision resolution.
//!
//! ## Thread safety
//!
//! `MapState` is `Send + Sync`.  The facade crate's [`MapHandle`]
//! wraps it in an `RwLock`, giving shared read access for renderers
//! and exclusive write access for the input / update path.
//!
//! ## Coordinate conventions
//!
//! All world-space positions are in **Web Mercator meters**, and the
//! camera uses a **camera-relative** origin to avoid f32 jitter at
//! large coordinates.  See the [`camera`](crate::camera) module docs
//! for the full coordinate-system description.
//!
//! [`MapHandle`]: https://docs.rs/rustial/latest/rustial/struct.MapHandle.html
// ---------------------------------------------------------------------------

use crate::async_data::{
    AsyncDataPipeline, DataTaskPool, TerrainTaskInput, VectorCacheKey,
    VectorTaskInput,
};
use crate::picking::{
    HitCategory, HitProvenance, PickHit, PickOptions, PickQuery, PickResult,
};
use crate::geometry::{FeatureCollection, PropertyValue};
use crate::layer::Layer;
use crate::layer::LayerId;
use crate::query::{
    feature_id_for_feature, geometry_hit_distance, FeatureState, FeatureStateId, QueriedFeature,
    QueryOptions,
};
use crate::camera::{Camera, CameraConstraints, CameraController, CameraMode};
use crate::camera_projection::CameraProjection;
use crate::camera_animator::CameraAnimator;
use crate::geo_wrap::wrap_lon_180;
use crate::input::InputEvent;
use crate::layers::{FeatureProvenance, LayerStack, VectorMeshData, VectorStyle};
use crate::models::ModelInstance;
use crate::style::{MapStyle, StyleDocument, StyleError};
use crate::streamed_payload::{
    collect_affected_symbol_payloads, prune_affected_symbol_payloads,
    resolve_streamed_vector_layer_refresh, StreamedPayloadView, StreamedSymbolPayloadKey,
    StreamedVectorLayerRefreshSpec, SymbolDependencyPayload, SymbolQueryPayload,
    TileQueryPayload, VisiblePlacedSymbolView, symbol_query_payloads_from_optional,
};
use crate::symbols::{PlacedSymbol, SymbolAssetRegistry, SymbolPlacementEngine};
use crate::loading_placeholder::{LoadingPlaceholder, PlaceholderGenerator, PlaceholderStyle};
use crate::terrain::{PreparedHillshadeRaster, TerrainConfig, TerrainManager, TerrainMeshData};
use crate::tile_manager::{VisibleTile, ZoomPrefetchDirection};
use crate::tile_cache::TileCacheStats;
use crate::tile_lifecycle::TileLifecycleDiagnostics;
use crate::tile_manager::{TileManagerCounters, TileSelectionStats};
use crate::tile_source::TileSourceDiagnostics;
use crate::tile_request_coordinator::{
    CoordinatorConfig, CoordinatorStats, SourcePriority, TileRequestCoordinator,
};
use rustial_math::{
    visible_tiles, visible_tiles_flat_view_with_config, FlatTileSelectionConfig, Frustum,
    GeoBounds, GeoCoord, TileId, WebMercator, WorldBounds, WorldCoord, MAX_ZOOM,
};
use std::collections::{HashMap, HashSet, VecDeque};
use std::sync::Arc;

mod picking;
mod tile_selection;
mod heavy_layers;
mod async_pipeline;
#[cfg(test)]
mod tests;

// ---------------------------------------------------------------------------
// Constants
// ---------------------------------------------------------------------------

/// Earth's equatorial circumference in meters (2*pi * WGS-84 semi-major axis).
///
/// Used to convert between camera `meters_per_pixel` and slippy-map zoom
/// levels.  Matches the constant embedded in [`WebMercator::world_size()`].
const WGS84_CIRCUMFERENCE: f64 = 2.0 * std::f64::consts::PI * 6_378_137.0;

/// Standard raster tile edge length in pixels (universal slippy-map
/// convention).
const TILE_PX: f64 = 256.0;

/// Fraction of a source budget that may be spent on speculative prefetch.
const SPECULATIVE_PREFETCH_BUDGET_FRACTION: f64 = 0.25;

/// Fallback speculative request cap when global coordination is disabled.
const DEFAULT_SPECULATIVE_PREFETCH_REQUEST_BUDGET: usize = 8;

/// Minimum fractional zoom change treated as intentional zoom motion.
const ZOOM_DIRECTION_PREFETCH_THRESHOLD: f64 = 0.01;

fn viewport_sample_points(width: f64, height: f64) -> Vec<(f64, f64)> {
    const FRACTIONS: [f64; 7] = [0.0, 1.0 / 6.0, 2.0 / 6.0, 0.5, 4.0 / 6.0, 5.0 / 6.0, 1.0];
    let mut samples = Vec::with_capacity(FRACTIONS.len() * FRACTIONS.len());
    for fy in FRACTIONS {
        for fx in FRACTIONS {
            samples.push((width * fx, height * fy));
        }
    }
    samples
}

fn perspective_viewport_overscan(pitch: f64) -> f64 {
    let normalized_pitch = (pitch / std::f64::consts::FRAC_PI_2).clamp(0.0, 1.0);
    1.3 + 0.5 * normalized_pitch
}

fn terrain_base_tile_budget(required_tiles: usize) -> usize {
    required_tiles.max(80).min(256)
}

fn terrain_horizon_tile_budget(base_budget: usize, pitch: f64) -> usize {
    if pitch <= 0.5 {
        0
    } else {
        (base_budget / 3).max(24).min(96)
    }
}

// ---------------------------------------------------------------------------
// FitBoundsOptions
// ---------------------------------------------------------------------------

/// Padding in logical pixels for [`MapState::fit_bounds`].
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FitBoundsPadding {
    /// Top padding in logical pixels.
    pub top: f64,
    /// Bottom padding in logical pixels.
    pub bottom: f64,
    /// Left padding in logical pixels.
    pub left: f64,
    /// Right padding in logical pixels.
    pub right: f64,
}

impl Default for FitBoundsPadding {
    fn default() -> Self {
        Self { top: 0.0, bottom: 0.0, left: 0.0, right: 0.0 }
    }
}

impl FitBoundsPadding {
    /// Uniform padding on all sides.
    pub fn uniform(px: f64) -> Self {
        Self { top: px, bottom: px, left: px, right: px }
    }
}

/// Options for [`MapState::fit_bounds`].
///
/// Mirrors MapLibre's `fitBounds` options.
#[derive(Debug, Clone)]
pub struct FitBoundsOptions {
    /// Padding in logical pixels.
    pub padding: FitBoundsPadding,
    /// Maximum zoom level to use. `None` = no cap.
    pub max_zoom: Option<f64>,
    /// Whether to animate the transition (fly-to). Default: `true`.
    pub animate: bool,
    /// Explicit animation duration in seconds. Only used when `animate` is `true`.
    pub duration: Option<f64>,
    /// Target bearing (yaw) in radians. `None` = keep current.
    pub bearing: Option<f64>,
    /// Target pitch in radians. `None` = keep current.
    pub pitch: Option<f64>,
}

impl Default for FitBoundsOptions {
    fn default() -> Self {
        Self {
            padding: FitBoundsPadding::default(),
            max_zoom: None,
            animate: true,
            duration: None,
            bearing: None,
            pitch: None,
        }
    }
}

// ---------------------------------------------------------------------------
// Sync-path vector tessellation cache
// ---------------------------------------------------------------------------

/// Cache key for the sync-path per-layer vector tessellation cache.
///
/// When no async pipeline is active, `update_heavy_layers` uses this cache
/// to skip re-tessellation when neither the style, the feature data, nor the
/// projection have changed since the last frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct SyncVectorCacheKey {
    /// Stable layer identity.
    layer_id: LayerId,
    /// Style fingerprint from [`VectorStyle::tessellation_fingerprint`].
    style_fingerprint: u64,
    /// Feature data generation counter.
    data_generation: u64,
    /// Projection at tessellation time.
    projection: CameraProjection,
}

/// Cached tessellation result for a single vector layer in the sync path.
#[derive(Clone)]
struct SyncVectorCacheEntry {
    mesh: VectorMeshData,
}

// ---------------------------------------------------------------------------
// FrameOutput
// ---------------------------------------------------------------------------

/// Bundled per-frame snapshot produced by [`MapState::update`] for renderers.
///
/// Contains **everything** a renderer needs to draw a single frame,
/// avoiding the need to reach into `MapState` internals.  All data is
/// owned (`Clone`d from `MapState`), so the struct can be sent to a
/// render thread without holding a lock.
///
/// # Usage
///
/// ```rust,ignore
/// state.update();
/// let frame = state.frame_output();
/// // Send `frame` to the GPU thread ...
/// ```
#[derive(Debug, Default)]
pub struct FrameOutput {
    /// View-projection matrix (f64 precision, camera-relative origin).
    ///
    /// Cast to `glam::Mat4` (f32) when uploading to a GPU uniform buffer.
    /// The f64 source preserves precision for CPU-side picking and culling.
    pub view_projection: glam::DMat4,

    /// View frustum planes for CPU-side culling.
    ///
    /// `None` only before the first call to `update()`.
    pub frustum: Option<Frustum>,

    /// Visible tiles (loaded imagery or parent-tile fallbacks).
    ///
    /// Wrapped in `Arc` for zero-copy sharing with render threads.
    pub tiles: Arc<Vec<VisibleTile>>,


    /// Terrain meshes to render (one per visible tile with elevation data).
    ///
    /// Wrapped in `Arc` for zero-copy sharing with render threads.
    pub terrain: Arc<Vec<TerrainMeshData>>,


    /// Prepared DEM-derived hillshade rasters aligned to the visible terrain set.
    pub hillshade: Arc<Vec<PreparedHillshadeRaster>>,

    /// Tessellated vector meshes (polygons, lines, points).
    ///
    /// Wrapped in `Arc` for zero-copy sharing with render threads.
    pub vectors: Arc<Vec<VectorMeshData>>, 

    /// Placed 3D model instances to render.
    ///
    /// Wrapped in `Arc` for zero-copy sharing with render threads.
    pub models: Arc<Vec<ModelInstance>>,

    /// Placed symbol instances after collision resolution.
    pub symbols: Arc<Vec<PlacedSymbol>>,

    /// Visualization overlay data (grids, columns, etc.) from the last update.
    pub visualization: Arc<Vec<crate::visualization::VisualizationOverlay>>,

    /// Loading placeholders for visible tiles that have no data yet.
    ///
    /// Renderers should draw styled rectangles at these world bounds
    /// before or behind the opaque tile pass so that loading areas
    /// never appear as blank gaps.
    pub placeholders: Arc<Vec<LoadingPlaceholder>>,

    /// Georeferenced image overlays (image/video/canvas sources).
    ///
    /// Each entry is a textured quad defined by four world-space corners
    /// plus RGBA8 pixel data.  Renderers should draw these between the
    /// tile and vector passes.
    pub image_overlays: Arc<Vec<crate::layers::ImageOverlayData>>,

    /// Current integer zoom level (0-22).
    pub zoom_level: u8,
}

/// Snapshot of the active tile-layer pipeline for debug/telemetry use.
#[derive(Debug, Clone, Default)]
pub struct TilePipelineDiagnostics {
    /// Name of the tile layer providing the snapshot.
    pub layer_name: String,
    /// Number of visible tiles in the layer's last visible set.
    pub visible_tiles: usize,
    /// Number of visible tiles with exact or fallback data loaded.
    pub visible_loaded_tiles: usize,
    /// Number of visible tiles currently using fallback imagery.
    pub visible_fallback_tiles: usize,
    /// Number of visible tiles with no imagery currently available.
    pub visible_missing_tiles: usize,
    /// Number of visible tiles rendered as overzoomed.
    pub visible_overzoomed_tiles: usize,
    /// Per-frame tile-selection stats from the last update.
    pub selection_stats: TileSelectionStats,
    /// Cumulative tile-manager counters.
    pub counters: TileManagerCounters,
    /// Current cache state counts.
    pub cache_stats: TileCacheStats,
    /// Optional source transport diagnostics.
    pub source_diagnostics: Option<TileSourceDiagnostics>,
}

/// Configuration for camera-motion sampling and look-ahead prediction.
#[derive(Debug, Clone, PartialEq)]
pub struct CameraVelocityConfig {
    /// Number of recent motion samples to retain.
    ///
    /// The effective velocity is computed from the oldest and newest retained
    /// samples, so larger windows smooth short spikes while smaller windows
    /// react more quickly to abrupt changes.
    pub sample_window: usize,
    /// Look-ahead time in seconds used to project the current pan motion.
    pub look_ahead_seconds: f64,
}

impl Default for CameraVelocityConfig {
    fn default() -> Self {
        Self {
            sample_window: 6,
            look_ahead_seconds: 0.5,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq)]
struct CameraMotionSample {
    time_seconds: f64,
    target_world: glam::DVec2,
}

/// Smoothed camera pan state derived from recent update frames.
#[derive(Debug, Clone, PartialEq)]
pub struct CameraMotionState {
    /// Smoothed pan velocity in Web Mercator meters per second.
    pub pan_velocity_world: glam::DVec2,
    /// Predicted camera target in Web Mercator meters after the configured
    /// look-ahead interval.
    pub predicted_target_world: glam::DVec2,
    /// Predicted viewport bounds translated by the same look-ahead motion.
    pub predicted_viewport_bounds: WorldBounds,
}

impl Default for CameraMotionState {
    fn default() -> Self {
        let zero = WorldCoord::new(0.0, 0.0, 0.0);
        Self {
            pan_velocity_world: glam::DVec2::ZERO,
            predicted_target_world: glam::DVec2::ZERO,
            predicted_viewport_bounds: WorldBounds::new(zero, zero),
        }
    }
}

// ---------------------------------------------------------------------------
// MapState
// ---------------------------------------------------------------------------

/// The central state object consumed by renderers each frame.
///
/// Owns the camera, layer stack, terrain manager, camera animator,
/// and all per-frame derived data (zoom level, viewport bounds,
/// frustum, mesh caches).
///
/// # Field visibility
///
/// All fields are private.  Use accessor methods for reads and
/// targeted setters for writes:
///
/// | Need | Method |
/// |------|--------|
/// | Read camera | [`camera()`](Self::camera) |
/// | Set viewport size | [`set_viewport`](Self::set_viewport) |
/// | Set camera target | [`set_camera_target`](Self::set_camera_target) |
/// | Set camera distance | [`set_camera_distance`](Self::set_camera_distance) |
/// | Set camera pitch/yaw | [`set_camera_pitch`](Self::set_camera_pitch), [`set_camera_yaw`](Self::set_camera_yaw) |
/// | Toggle projection | [`set_camera_mode`](Self::set_camera_mode) |
/// | Set camera FOV | [`set_camera_fov_y`](Self::set_camera_fov_y) |
/// | Read constraints | [`constraints()`](Self::constraints) |
/// | Set max pitch | [`set_max_pitch`](Self::set_max_pitch) |
/// | Add a layer | [`push_layer`](Self::push_layer) |
/// | Read layers | [`layers()`](Self::layers) |
/// | Read vector meshes | [`vector_meshes()`](Self::vector_meshes) |
/// | Read model instances | [`model_instances()`](Self::model_instances) |
/// | Dispatch input | [`handle_input`](Self::handle_input) |
/// | Animate camera | [`fly_to`](Self::fly_to) |
/// | Check animator | [`animator()`](Self::animator) |
/// | Replace terrain | [`set_terrain`](Self::set_terrain) |
/// | Read terrain state | [`terrain()`](Self::terrain) |
pub struct MapState {
    // -- Inputs -----------------------------------------------------------

    /// Camera controlling the view (target, orbit params, projection).
    camera: Camera,

    /// Per-frame clamps applied to the camera by [`CameraController`](crate::CameraController).
    constraints: CameraConstraints,

    /// Ordered layer stack (rendered bottom-to-top).
    pub(crate) layers: LayerStack,

    /// Optional style/runtime document that produced the current layer stack.
    style: Option<MapStyle>,

    /// Terrain elevation manager.
    pub(crate) terrain: TerrainManager,

    /// Camera animator for smooth zoom, rotation, and pan momentum.
    animator: CameraAnimator,

    // -- Animation-aware data update throttle ------------------------------

    /// Minimum interval (seconds) between heavy layer updates (terrain
    /// meshing, vector tessellation, symbol placement, model collection)
    /// while a coordinated camera animation (fly-to / ease-to) is active.
    ///
    /// Tile layer updates (HTTP response polling, visible tile selection,
    /// and tile request issuing) always run every frame regardless of this
    /// interval, since they are lightweight and essential for keeping the
    /// visible tile set in sync with the camera.
    ///
    /// Default: `0.15` (~6-7 heavy data updates per second during animation).
    /// Set to `0.0` to disable throttling (matches the MapLibre model of
    /// updating every frame, but may cause stutter with heavy layers).
    ///
    /// **Note:** When an async task pool is active (see
    /// [`set_task_pool`](Self::set_task_pool)), this interval is ignored
    /// because dispatch + poll is cheap regardless of animation state.
    data_update_interval: f64,

    /// Accumulated time since the last full data update during animation.
    data_update_elapsed: f64,

    // -- Async retained data pipeline ------------------------------------

    /// Optional async data pipeline for offloading heavy CPU work.
    ///
    /// When set, `update_with_dt` dispatches terrain/vector/symbol work
    /// to background tasks and polls completed results each frame, matching
    /// the MapLibre/Mapbox web worker model.
    ///
    /// When `None`, the engine falls back to synchronous inline execution.
    async_pipeline: Option<AsyncDataPipeline>,

    // -- Per-frame derived state (private, recomputed by update) -----------

    /// Current integer zoom level (derived from `camera.meters_per_pixel()`).
    zoom_level: u8,

    /// Viewport bounding box in Web Mercator world space.
    viewport_bounds: WorldBounds,

    /// Viewport bounding box in the active planar scene projection.
    scene_viewport_bounds: WorldBounds,

    /// View frustum planes (derived from the camera VP matrix).
    frustum: Option<Frustum>,

    /// Terrain meshes produced during this frame's `update()`.
    terrain_meshes: Arc<Vec<TerrainMeshData>>,

    /// Manual terrain output override to apply after the next update cycle.
    pending_terrain_meshes: Option<Arc<Vec<TerrainMeshData>>>,


    /// Prepared hillshade rasters for the last `update()`.
    hillshade_rasters: Arc<Vec<PreparedHillshadeRaster>>,


    /// Visible tiles produced by the tile layer (or set externally).
    visible_tiles: Arc<Vec<VisibleTile>>,


    // -- Per-frame layer output -------------------------------------------

    /// Tessellated vector meshes from the last `update()`.
    pub(crate) vector_meshes: Arc<Vec<VectorMeshData>>,

    /// Manual vector output override to apply after the next update cycle.
    pending_vector_meshes: Option<Arc<Vec<VectorMeshData>>>,


    /// 3D model instances collected from all visible
    /// [`ModelLayer`](crate::layers::ModelLayer)s during the last `update()`.
    pub(crate) model_instances: Arc<Vec<ModelInstance>>,

    /// Manual model output override to apply after the next update cycle.
    pending_model_instances: Option<Arc<Vec<ModelInstance>>>,

    /// Placed symbols after collision resolution.
    placed_symbols: Arc<Vec<PlacedSymbol>>,


    /// Symbol asset dependency state derived from placed symbols.
    symbol_assets: SymbolAssetRegistry,

    /// Stateful symbol placement engine.
    symbol_placement: SymbolPlacementEngine,

    /// Mutable per-feature state keyed by source id and feature id.
    feature_state: HashMap<FeatureStateId, FeatureState>,

    /// Hidden style-owned streamed vector source runtimes keyed by source id.
    streamed_vector_sources: HashMap<String, crate::layers::TileLayer>,

    /// Last per-style-layer streamed vector fingerprint used to detect data changes.
    streamed_vector_layer_fingerprints: HashMap<String, u64>,

    /// Tile-owned query payloads for streamed vector style layers.
    streamed_vector_query_payloads: HashMap<String, Vec<TileQueryPayload>>,

    /// Tile-owned symbol query payloads grouped by style layer.
    streamed_symbol_query_payloads: HashMap<String, Vec<SymbolQueryPayload>>,

    /// Tile-owned symbol dependency payloads grouped by style layer.
    streamed_symbol_dependency_payloads: HashMap<String, Vec<SymbolDependencyPayload>>,

    /// Streamed symbol layers that must regenerate on the next update.
    dirty_streamed_symbol_layers: HashSet<String>,

    /// Streamed symbol tiles that must regenerate on the next update.
    dirty_streamed_symbol_tiles: HashMap<String, HashSet<TileId>>,

    /// Visualization overlays collected from the layer stack.
    visualization_overlays: Arc<Vec<crate::visualization::VisualizationOverlay>>,

    /// Image overlays collected from the layer stack.
    image_overlays: Arc<Vec<crate::layers::ImageOverlayData>>,

    /// Active placeholder style applied to loading tiles.
    placeholder_style: PlaceholderStyle,

    /// Loading placeholders from the last update.
    loading_placeholders: Arc<Vec<LoadingPlaceholder>>,

    /// Monotonic time accumulator (seconds) for placeholder animation.
    placeholder_time: f64,

    /// Optional engine-owned interaction manager for automatic hover/leave/click
    /// lifecycle bookkeeping. Set via [`set_interaction_manager`](Self::set_interaction_manager).
    interaction_manager: Option<crate::interaction_manager::InteractionManager>,

    /// Sync-path per-layer vector tessellation cache.
    ///
    /// When no async pipeline is active, [`update_heavy_layers`](Self::update_heavy_layers)
    /// stores the most recent tessellation result per layer here and reuses it
    /// when neither the style, the feature data, nor the projection have changed.
    sync_vector_cache: HashMap<SyncVectorCacheKey, SyncVectorCacheEntry>,

    /// Cross-source tile request coordinator.
    ///
    /// Distributes a global per-frame request budget among raster, vector,
    /// and terrain tile sources so they don't compete for bandwidth.
    /// See [`TileRequestCoordinator`] for details.
    request_coordinator: TileRequestCoordinator,

    /// Camera-motion sampling and look-ahead configuration.
    camera_velocity_config: CameraVelocityConfig,

    /// Monotonic clock used for camera-motion sampling.
    camera_motion_time_seconds: f64,

    /// Recent camera-target samples in Web Mercator world space.
    camera_motion_samples: VecDeque<CameraMotionSample>,

    /// Smoothed camera pan velocity and translated viewport prediction.
    camera_motion_state: CameraMotionState,

    /// Per-frame fractional zoom delta used for zoom-direction prefetch.
    camera_zoom_delta: f64,

    /// Previous fractional zoom sample for zoom-direction tracking.
    previous_fractional_zoom: Option<f64>,

    /// Optional navigation route polyline for route-aware tile prefetch.
    ///
    /// When set, the tile update loop speculatively prefetches tiles along
    /// this route ahead of the camera position, spending any remaining
    /// speculative budget after viewport and zoom-direction prefetch.
    prefetch_route: Option<Vec<GeoCoord>>,

    /// Callback-based event subscription emitter.
    ///
    /// Events drained from the [`InteractionManager`] are dispatched to
    /// registered listeners each frame, in addition to being available
    /// via the poll-based [`drain_events`] path.
    event_emitter: crate::event_emitter::EventEmitter,

    /// Multi-touch gesture recognizer.
    ///
    /// Converts raw [`TouchContact`](crate::input::TouchContact) events
    /// into pan / zoom / rotate [`InputEvent`]s.
    gesture_recognizer: crate::gesture::GestureRecognizer,

    /// Optional user fog/atmosphere override.
    fog_config: Option<crate::style::FogConfig>,

    /// Pre-computed fog parameters for the current frame.
    computed_fog: crate::style::ComputedFog,
}

// ---------------------------------------------------------------------------
// Default
// ---------------------------------------------------------------------------

impl Default for MapState {
    fn default() -> Self {
        let zero = WorldCoord::new(0.0, 0.0, 0.0);
        Self {
            camera: Camera::default(),
            constraints: CameraConstraints::default(),
            layers: LayerStack::new(),
            style: None,
            terrain: TerrainManager::new(TerrainConfig::default(), 256),
            animator: CameraAnimator::new(),
            data_update_interval: 0.15,
            data_update_elapsed: 0.0,
            async_pipeline: None,
            zoom_level: 0,
            viewport_bounds: WorldBounds::new(zero, zero),
            scene_viewport_bounds: WorldBounds::new(zero, zero),
            frustum: None,
            terrain_meshes: Arc::new(Vec::new()),
            pending_terrain_meshes: None,
            hillshade_rasters: Arc::new(Vec::new()),
            visible_tiles: Arc::new(Vec::new()),
            vector_meshes: Arc::new(Vec::new()),
            pending_vector_meshes: None,
            model_instances: Arc::new(Vec::new()),
            pending_model_instances: None,
            placed_symbols: Arc::new(Vec::new()),
            symbol_assets: SymbolAssetRegistry::new(),
            symbol_placement: SymbolPlacementEngine::new(),
            feature_state: HashMap::new(),
            streamed_vector_sources: HashMap::new(),
            streamed_vector_layer_fingerprints: HashMap::new(),
            streamed_vector_query_payloads: HashMap::new(),
            streamed_symbol_query_payloads: HashMap::new(),
            streamed_symbol_dependency_payloads: HashMap::new(),
            dirty_streamed_symbol_layers: HashSet::new(),
            dirty_streamed_symbol_tiles: HashMap::new(),
            visualization_overlays: Arc::new(Vec::new()),
            image_overlays: Arc::new(Vec::new()),
            placeholder_style: PlaceholderStyle::default(),
            loading_placeholders: Arc::new(Vec::new()),
            placeholder_time: 0.0,
            interaction_manager: None,
            sync_vector_cache: HashMap::new(),
            request_coordinator: TileRequestCoordinator::default(),
            camera_velocity_config: CameraVelocityConfig::default(),
            camera_motion_time_seconds: 0.0,
            camera_motion_samples: VecDeque::new(),
            camera_motion_state: CameraMotionState::default(),
            camera_zoom_delta: 0.0,
            previous_fractional_zoom: None,
            prefetch_route: None,
            event_emitter: crate::event_emitter::EventEmitter::new(),
            gesture_recognizer: crate::gesture::GestureRecognizer::new(),
            fog_config: None,
            computed_fog: crate::style::ComputedFog::default(),
        }
    }
}

// ---------------------------------------------------------------------------
// Construction
// ---------------------------------------------------------------------------

impl MapState {
    /// Create a new map state with default camera and no terrain.
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a map state with terrain support.
    ///
    /// # Arguments
    ///
    /// - `terrain_config` -- Terrain settings (enabled flag, mesh resolution,
    ///   elevation source, vertical exaggeration, skirt depth).
    /// - `terrain_cache_size` -- Maximum number of elevation grids to keep
    ///   in the LRU cache.
    pub fn with_terrain(terrain_config: TerrainConfig, terrain_cache_size: usize) -> Self {
        let zero = WorldCoord::new(0.0, 0.0, 0.0);
        Self {
            camera: Camera::default(),
            constraints: CameraConstraints::default(),
            layers: LayerStack::new(),
            style: None,
            terrain: TerrainManager::new(terrain_config, terrain_cache_size),
            animator: CameraAnimator::new(),
            data_update_interval: 0.15,
            data_update_elapsed: 0.0,
            async_pipeline: None,
            zoom_level: 0,
            viewport_bounds: WorldBounds::new(zero, zero),
            scene_viewport_bounds: WorldBounds::new(zero, zero),
            frustum: None,
            terrain_meshes: Arc::new(Vec::new()),
            pending_terrain_meshes: None,
            hillshade_rasters: Arc::new(Vec::new()),
            visible_tiles: Arc::new(Vec::new()),
            vector_meshes: Arc::new(Vec::new()),
            pending_vector_meshes: None,
            model_instances: Arc::new(Vec::new()),
            pending_model_instances: None,
            placed_symbols: Arc::new(Vec::new()),
            symbol_assets: SymbolAssetRegistry::new(),
            symbol_placement: SymbolPlacementEngine::new(),
            feature_state: HashMap::new(),
            streamed_vector_sources: HashMap::new(),
            streamed_vector_layer_fingerprints: HashMap::new(),
            streamed_vector_query_payloads: HashMap::new(),
            streamed_symbol_query_payloads: HashMap::new(),
            streamed_symbol_dependency_payloads: HashMap::new(),
            dirty_streamed_symbol_layers: HashSet::new(),
            dirty_streamed_symbol_tiles: HashMap::new(),
            visualization_overlays: Arc::new(Vec::new()),
            image_overlays: Arc::new(Vec::new()),
            placeholder_style: PlaceholderStyle::default(),
            loading_placeholders: Arc::new(Vec::new()),
            placeholder_time: 0.0,
            interaction_manager: None,
            sync_vector_cache: HashMap::new(),
            request_coordinator: TileRequestCoordinator::default(),
            camera_velocity_config: CameraVelocityConfig::default(),
            camera_motion_time_seconds: 0.0,
            camera_motion_samples: VecDeque::new(),
            camera_motion_state: CameraMotionState::default(),
            camera_zoom_delta: 0.0,
            previous_fractional_zoom: None,
            prefetch_route: None,
            event_emitter: crate::event_emitter::EventEmitter::new(),
            gesture_recognizer: crate::gesture::GestureRecognizer::new(),
            fog_config: None,
            computed_fog: crate::style::ComputedFog::default(),
        }
    }

    // -- Accessors (derived state) ----------------------------------------

    /// Current integer zoom level (0-22).
    ///
    /// Derived from [`Camera::meters_per_pixel`] during [`update`](Self::update).
    /// Returns `0` before the first update.
    #[inline]
    pub fn zoom_level(&self) -> u8 {
        self.zoom_level
    }

    /// Continuous fractional zoom level (e.g. `8.73`).
    ///
    /// Derived from [`Camera::near_meters_per_pixel`] using the same
    /// formula as [`zoom_level`](Self::zoom_level), but without rounding
    /// to an integer.  Useful for debug displays and smooth zoom
    /// interpolation.
    #[inline]
    pub fn fractional_zoom(&self) -> f64 {
        let mpp = self.camera.near_meters_per_pixel();
        if mpp <= 0.0 || !mpp.is_finite() {
            return MAX_ZOOM as f64;
        }
        (WGS84_CIRCUMFERENCE / (mpp * TILE_PX)).log2().clamp(0.0, MAX_ZOOM as f64)
    }

    /// Viewport bounding box in Web Mercator world space from the last
    /// [`update`](Self::update).
    ///
    /// Includes an overscan margin for tile prefetching.
    #[inline]
    pub fn viewport_bounds(&self) -> &WorldBounds {
        &self.viewport_bounds
    }

    /// Read-only access to the camera-motion prediction configuration.
    #[inline]
    pub fn camera_velocity_config(&self) -> &CameraVelocityConfig {
        &self.camera_velocity_config
    }

    /// Replace the camera-motion prediction configuration.
    pub fn set_camera_velocity_config(&mut self, config: CameraVelocityConfig) {
        self.camera_velocity_config = config;
        self.trim_camera_motion_samples();
        self.recompute_camera_motion_state();
    }

    /// Smoothed camera pan velocity and translated viewport prediction.
    #[inline]
    pub fn camera_motion_state(&self) -> &CameraMotionState {
        &self.camera_motion_state
    }

    /// Predicted viewport bounds after the configured look-ahead interval.
    #[inline]
    pub fn predicted_viewport_bounds(&self) -> &WorldBounds {
        &self.camera_motion_state.predicted_viewport_bounds
    }

    /// Viewport bounding box in the active planar scene projection.
    #[inline]
    pub fn scene_viewport_bounds(&self) -> &WorldBounds {
        &self.scene_viewport_bounds
    }

    /// View frustum from the last [`update`](Self::update).
    ///
    /// `None` only before the first `update()` call.
    #[inline]
    pub fn frustum(&self) -> Option<&Frustum> {
        self.frustum.as_ref()
    }

    /// Renderer/world origin used by the current render compatibility path.
    ///
    /// This remains Web Mercator backed for the current raster/terrain stack,
    /// even when the camera itself uses a different planar projection.
    #[inline]
    pub fn renderer_world_origin(&self) -> glam::DVec3 {
        let (x, y) = self.mercator_camera_world();
        glam::DVec3::new(x, y, 0.0)
    }

    /// Active scene origin in the camera's currently selected planar
    /// projection.
    ///
    /// Projection-specialized geometry paths such as terrain, vectors,
    /// symbols, models, and Bevy geo-entities should use this origin so
    /// their world coordinates remain aligned under non-Mercator planar
    /// projections.
    #[inline]
    pub fn scene_world_origin(&self) -> glam::DVec3 {
        self.camera.target_world()
    }

    /// Terrain meshes produced during the last [`update`](Self::update).
    ///
    /// Empty when terrain is disabled or no elevation data is cached.
    #[inline]
    pub fn terrain_meshes(&self) -> &[TerrainMeshData] {
        &self.terrain_meshes
    }

    /// Prepared DEM-derived hillshade rasters from the last update.
    #[inline]
    pub fn hillshade_rasters(&self) -> &[PreparedHillshadeRaster] {
        &self.hillshade_rasters
    }

    /// Visible tiles from the last [`update`](Self::update).
    #[inline]
    pub fn visible_tiles(&self) -> &[VisibleTile] {
        &self.visible_tiles
    }

    /// Loading placeholders from the last [`update`](Self::update).
    ///
    /// One entry per visible tile that has no data yet.  Empty when all
    /// visible tiles are loaded.
    #[inline]
    pub fn loading_placeholders(&self) -> &[LoadingPlaceholder] {
        &self.loading_placeholders
    }

    /// Active placeholder style.
    #[inline]
    pub fn placeholder_style(&self) -> &PlaceholderStyle {
        &self.placeholder_style
    }

    /// Replace the placeholder style.
    pub fn set_placeholder_style(&mut self, style: PlaceholderStyle) {
        self.placeholder_style = style;
    }

    /// Read-only access to the cross-source tile request coordinator's
    /// most recent diagnostics.
    pub fn coordinator_stats(&self) -> &CoordinatorStats {
        self.request_coordinator.stats()
    }

    /// Read-only access to the cross-source coordinator configuration.
    pub fn coordinator_config(&self) -> &CoordinatorConfig {
        self.request_coordinator.config()
    }

    /// Replace the cross-source coordinator configuration.
    ///
    /// Takes effect on the next frame.  Set `global_request_budget` to
    /// 0 to disable coordination entirely.
    pub fn set_coordinator_config(&mut self, config: CoordinatorConfig) {
        self.request_coordinator.set_config(config);
    }

    /// Set an optional navigation route for route-aware tile prefetch.
    ///
    /// When set, the tile update loop will speculatively prefetch tiles
    /// along the route ahead of the current camera position, spending
    /// remaining speculative budget after viewport-prediction and
    /// zoom-direction prefetch.
    ///
    /// The route should be a polyline of geographic coordinates ordered
    /// from origin to destination.  Pass an empty slice or call
    /// [`clear_prefetch_route`](Self::clear_prefetch_route) to disable.
    pub fn set_prefetch_route(&mut self, route: Vec<GeoCoord>) {
        if route.len() < 2 {
            self.prefetch_route = None;
        } else {
            self.prefetch_route = Some(route);
        }
    }

    /// Clear the navigation route used for route-aware tile prefetch.
    pub fn clear_prefetch_route(&mut self) {
        self.prefetch_route = None;
    }

    /// Read-only access to the active prefetch route, if any.
    #[inline]
    pub fn prefetch_route(&self) -> Option<&[GeoCoord]> {
        self.prefetch_route.as_deref()
    }

    /// Return a diagnostics snapshot for the first visible tile layer, if any.
    pub fn tile_pipeline_diagnostics(&self) -> Option<TilePipelineDiagnostics> {
        use crate::layers::TileLayer;

        for layer in self.layers.iter() {
            if !layer.visible() {
                continue;
            }
            let Some(tile_layer) = layer.as_any().downcast_ref::<TileLayer>() else {
                continue;
            };

            let visible = tile_layer.visible_tiles();
            let visible_loaded_tiles = visible.tiles.iter().filter(|tile| tile.data.is_some()).count();
            let visible_fallback_tiles = visible.tiles.iter().filter(|tile| tile.is_fallback() && tile.data.is_some()).count();
            let visible_missing_tiles = visible.tiles.iter().filter(|tile| tile.data.is_none()).count();
            let visible_overzoomed_tiles = visible.tiles.iter().filter(|tile| tile.is_overzoomed()).count();

            return Some(TilePipelineDiagnostics {
                layer_name: tile_layer.name().to_owned(),
                visible_tiles: visible.len(),
                visible_loaded_tiles,
                visible_fallback_tiles,
                visible_missing_tiles,
                visible_overzoomed_tiles,
                selection_stats: tile_layer.last_selection_stats().clone(),
                counters: tile_layer.counters().clone(),
                cache_stats: tile_layer.cache_stats(),
                source_diagnostics: tile_layer.source_diagnostics(),
            });
        }

        None
    }

    /// Return recent tile lifecycle diagnostics for the first visible tile layer, if any.
    pub fn tile_lifecycle_diagnostics(&self) -> Option<TileLifecycleDiagnostics> {
        use crate::layers::TileLayer;

        for layer in self.layers.iter() {
            if !layer.visible() {
                continue;
            }
            let Some(tile_layer) = layer.as_any().downcast_ref::<TileLayer>() else {
                continue;
            };
            return Some(tile_layer.lifecycle_diagnostics());
        }

        None
    }

    /// Return the effective background Colour from the top-most visible
    /// [`BackgroundLayer`](crate::layers::BackgroundLayer), if any.
    ///
    /// This gives renderers a backend-owned clear colour similar to
    /// MapLibre's background layer instead of relying only on hard-coded
    /// renderer defaults.
    pub fn background_color(&self) -> Option<[f32; 4]> {
        use crate::layers::BackgroundLayer;

        let mut color = None;
        for layer in self.layers.iter() {
            if !layer.visible() {
                continue;
            }
            if let Some(background) = layer.as_any().downcast_ref::<BackgroundLayer>() {
                color = Some(background.effective_color());
            }
        }
        color
    }

    /// Return the effective hillshade parameters from the top-most visible
    /// [`HillshadeLayer`](crate::layers::HillshadeLayer), if any.
    pub fn hillshade(&self) -> Option<crate::layers::HillshadeParams> {
        use crate::layers::HillshadeLayer;

        let mut params = None;
        for layer in self.layers.iter() {
            if !layer.visible() {
                continue;
            }
            if let Some(hillshade) = layer.as_any().downcast_ref::<HillshadeLayer>() {
                params = Some(hillshade.effective_params());
            }
        }
        params
    }

    /// Set the fog/atmosphere configuration override.
    ///
    /// When set, the provided [`FogConfig`](crate::style::FogConfig) values
    /// override the automatic pitch-based fog computation.  `None` fields
    /// in the config fall back to the auto-computed defaults.
    ///
    /// Pass `None` to revert to fully automatic fog.
    pub fn set_fog(&mut self, config: Option<crate::style::FogConfig>) {
        self.fog_config = config;
    }

    /// Return the current fog configuration override, if any.
    pub fn fog(&self) -> Option<&crate::style::FogConfig> {
        self.fog_config.as_ref()
    }

    /// Return the pre-computed fog parameters for the current frame.
    ///
    /// These are recomputed each frame during [`update()`](Self::update)
    /// from camera state, the optional [`FogConfig`](crate::style::FogConfig),
    /// and the background colour.  Renderers should read these values
    /// directly instead of duplicating the fog math.
    pub fn computed_fog(&self) -> &crate::style::ComputedFog {
        &self.computed_fog
    }

    /// Override the visible tile set for this frame.
    pub fn set_visible_tiles(&mut self, tiles: Vec<VisibleTile>) {
        self.visible_tiles = Arc::new(tiles);
    }

    /// Override the terrain meshes for this frame (useful for testing).
    pub fn set_terrain_meshes(&mut self, meshes: Vec<TerrainMeshData>) {
        let meshes = Arc::new(meshes);
        self.pending_terrain_meshes = Some(meshes.clone());
        self.terrain_meshes = meshes;
    }

    /// Override the prepared hillshade rasters for this frame (useful for testing).
    pub fn set_hillshade_rasters(&mut self, rasters: Vec<PreparedHillshadeRaster>) {
        self.hillshade_rasters = Arc::new(rasters);
    }

    // -- Camera accessors -------------------------------------------------

    /// Immutable reference to the camera.
    #[inline]
    pub fn camera(&self) -> &Camera {
        &self.camera
    }

    /// Set the camera viewport dimensions (logical pixels).
    pub fn set_viewport(&mut self, width: u32, height: u32) {
        self.camera.set_viewport(width, height);
    }

    /// Set the camera target geographic coordinate.
    ///
    /// Longitude is normalized to `[-180, 180)` to prevent the camera
    /// from drifting into a different world copy, which would cause
    /// tile selection to diverge and tiles to stop rendering.
    pub fn set_camera_target(&mut self, target: GeoCoord) {
        if !target.lat.is_finite() || !target.lon.is_finite() {
            return;
        }
        let wrapped = GeoCoord::from_lat_lon(target.lat, wrap_lon_180(target.lon));
        self.camera.set_target(wrapped);
    }

    /// Set the camera distance from the target in meters.
    pub fn set_camera_distance(&mut self, distance: f64) {
        if !distance.is_finite() || distance <= 0.0 {
            return;
        }
        self.camera.set_distance(distance);
    }

    /// Set the camera pitch in radians.
    pub fn set_camera_pitch(&mut self, pitch: f64) {
        if !pitch.is_finite() {
            return;
        }
        self.camera.set_pitch(pitch);
    }

    /// Set the camera yaw / bearing in radians.
    pub fn set_camera_yaw(&mut self, yaw: f64) {
        if !yaw.is_finite() {
            return;
        }
        self.camera.set_yaw(yaw);
    }

    /// Set the camera projection mode (perspective / orthographic).
    pub fn set_camera_mode(&mut self, mode: CameraMode) {
        self.camera.set_mode(mode);
    }

    /// Set the camera geographic projection used by camera/world helpers.
    pub fn set_camera_projection(&mut self, projection: CameraProjection) {
        self.camera.set_projection(projection);
    }

    /// Set the vertical field-of-view in radians (perspective mode).
    pub fn set_camera_fov_y(&mut self, fov_y: f64) {
        if !fov_y.is_finite() || fov_y <= 0.0 {
            return;
        }
        self.camera.set_fov_y(fov_y);
    }

    // -- Constraint accessors ---------------------------------------------

    /// Immutable reference to the camera constraints.
    #[inline]
    pub fn constraints(&self) -> &CameraConstraints {
        &self.constraints
    }

    /// Set the maximum camera pitch in radians.
    pub fn set_max_pitch(&mut self, max_pitch: f64) {
        if !max_pitch.is_finite() || max_pitch <= 0.0 {
            return;
        }
        self.constraints.max_pitch = max_pitch;
    }

    /// Set the minimum camera distance in meters.
    pub fn set_min_distance(&mut self, min_distance: f64) {
        if !min_distance.is_finite() || min_distance <= 0.0 {
            return;
        }
        self.constraints.min_distance = min_distance;
    }

    /// Set the maximum camera distance in meters.
    pub fn set_max_distance(&mut self, max_distance: f64) {
        if !max_distance.is_finite() || max_distance <= 0.0 {
            return;
        }
        self.constraints.max_distance = max_distance;
    }

    // -- Layer accessors---------------------------------------------------

    /// Immutable reference to the layer stack.
    #[inline]
    pub fn layers(&self) -> &LayerStack {
        &self.layers
    }

    /// Add a layer to the top of the stack.
    pub fn push_layer(&mut self, layer: Box<dyn crate::layer::Layer>) {
        self.layers.push(layer);
        self.style = None;
    }

    /// Insert or replace a named grid-scalar visualization layer.
    pub fn set_grid_scalar(
        &mut self,
        name: impl Into<String>,
        grid: crate::visualization::GeoGrid,
        field: crate::visualization::ScalarField2D,
        ramp: crate::visualization::ColorRamp,
    ) {
        let name = name.into();
        if let Some(index) = self.layers.index_of(&name) {
            if let Some(layer) = self.layers.get_mut(index) {
                if let Some(existing) = layer
                    .as_any_mut()
                    .downcast_mut::<crate::visualization::GridScalarLayer>()
                {
                    existing.grid = grid;
                    existing.field = field;
                    existing.ramp = ramp;
                    self.style = None;
                    return;
                }
            }
        }
        let layer = Box::new(crate::visualization::GridScalarLayer::new(
            name.clone(),
            grid,
            field,
            ramp,
        ));
        self.replace_or_push_named_layer(&name, layer);
    }

    /// Insert or replace a named grid-extrusion visualization layer.
    pub fn set_grid_extrusion(
        &mut self,
        name: impl Into<String>,
        grid: crate::visualization::GeoGrid,
        field: crate::visualization::ScalarField2D,
        ramp: crate::visualization::ColorRamp,
        params: crate::visualization::ExtrusionParams,
    ) {
        let name = name.into();
        if let Some(index) = self.layers.index_of(&name) {
            if let Some(layer) = self.layers.get_mut(index) {
                if let Some(existing) = layer
                    .as_any_mut()
                    .downcast_mut::<crate::visualization::GridExtrusionLayer>()
                {
                    existing.grid = grid;
                    existing.field = field;
                    existing.ramp = ramp;
                    existing.params = params;
                    self.style = None;
                    return;
                }
            }
        }
        let layer = Box::new(
            crate::visualization::GridExtrusionLayer::new(name.clone(), grid, field, ramp)
                .with_params(params),
        );
        self.replace_or_push_named_layer(&name, layer);
    }

    /// Insert or replace a named instanced-column visualization layer.
    pub fn set_instanced_columns(
        &mut self,
        name: impl Into<String>,
        columns: crate::visualization::ColumnInstanceSet,
        ramp: crate::visualization::ColorRamp,
    ) {
        let name = name.into();
        if let Some(index) = self.layers.index_of(&name) {
            if let Some(layer) = self.layers.get_mut(index) {
                if let Some(existing) = layer
                    .as_any_mut()
                    .downcast_mut::<crate::visualization::InstancedColumnLayer>()
                {
                    existing.columns = columns;
                    existing.ramp = ramp;
                    self.style = None;
                    return;
                }
            }
        }
        let layer = Box::new(crate::visualization::InstancedColumnLayer::new(
            name.clone(),
            columns,
            ramp,
        ));
        self.replace_or_push_named_layer(&name, layer);
    }

    /// Insert or replace a named point-cloud visualization layer.
    pub fn set_point_cloud(
        &mut self,
        name: impl Into<String>,
        points: crate::visualization::PointInstanceSet,
        ramp: crate::visualization::ColorRamp,
    ) {
        let name = name.into();
        if let Some(index) = self.layers.index_of(&name) {
            if let Some(layer) = self.layers.get_mut(index) {
                if let Some(existing) = layer
                    .as_any_mut()
                    .downcast_mut::<crate::visualization::PointCloudLayer>()
                {
                    existing.points = points;
                    existing.ramp = ramp;
                    self.style = None;
                    return;
                }
            }
        }
        let layer = Box::new(crate::visualization::PointCloudLayer::new(
            name.clone(),
            points,
            ramp,
        ));
        self.replace_or_push_named_layer(&name, layer);
    }

    /// Return the currently attached style, if any.
    #[inline]
    pub fn style(&self) -> Option<&MapStyle> {
        self.style.as_ref()
    }

    /// Return the currently attached style document, if any.
    #[inline]
    pub fn style_document(&self) -> Option<&StyleDocument> {
        self.style.as_ref().map(MapStyle::document)
    }

    /// Replace the current style runtime and re-evaluate terrain + layer state.
    pub fn set_style(&mut self, style: MapStyle) -> Result<(), StyleError> {
        self.apply_style_document(style.document())?;
        self.style = Some(style);
        Ok(())
    }

    /// Replace the current style document and re-evaluate terrain + layer state.
    pub fn set_style_document(&mut self, document: StyleDocument) -> Result<(), StyleError> {
        self.set_style(MapStyle::from_document(document))
    }

    /// Mutate the current style document in place and then re-apply it.
    pub fn with_style_mut<R>(
        &mut self,
        mutate: impl FnOnce(&mut StyleDocument) -> R,
    ) -> Result<Option<R>, StyleError> {
        let mut style: MapStyle = match self.style.take() {
            Some(s) => s,
            None => return Ok(None),
        };
        let result = mutate(style.document_mut());
        self.apply_style_document(style.document())?;
        self.style = Some(style);
        Ok(Some(result))
    }

    /// Re-evaluate the currently attached style document, if any.
    pub fn reapply_style(&mut self) -> Result<bool, StyleError> {
        let style: MapStyle = match self.style.take() {
            Some(s) => s,
            None => return Ok(false),
        };
        self.apply_style_document(style.document())?;
        self.style = Some(style);
        Ok(true)
    }

    // -- Terrain accessors ------------------------------------------------

    /// Immutable reference to the terrain manager.
    #[inline]
    pub fn terrain(&self) -> &TerrainManager {
        &self.terrain
    }

    /// Replace the terrain manager with a new configuration.
    pub fn set_terrain(&mut self, terrain: TerrainManager) {
        self.terrain = terrain;
        if self.style.is_some() {
            self.style = None;
        }
    }

    // -- Animator accessor ------------------------------------------------

    /// Immutable reference to the camera animator.
    #[inline]
    pub fn animator(&self) -> &CameraAnimator {
        &self.animator
    }

    /// Whether any camera animation is currently active.
    #[inline]
    pub fn is_animating(&self) -> bool {
        self.animator.is_active()
    }

    // -- Data update throttle during animation ----------------------------

    /// Set the minimum interval (seconds) between full terrain + layer
    /// updates while a coordinated camera animation is active.
    pub fn set_data_update_interval(&mut self, interval: f64) {
        self.data_update_interval = interval.max(0.0);
    }

    /// Current data-update throttle interval in seconds.
    #[inline]
    pub fn data_update_interval(&self) -> f64 {
        self.data_update_interval
    }

    // -- Async task pool --------------------------------------------------

    /// Inject an async task pool for offloading heavy data pipeline work.
    pub fn set_task_pool(&mut self, pool: Arc<dyn DataTaskPool>) {
        self.async_pipeline = Some(AsyncDataPipeline::new(pool));
    }

    /// Remove the async task pool, reverting to synchronous execution.
    pub fn clear_task_pool(&mut self) {
        self.async_pipeline = None;
    }

    /// Whether an async task pool is currently active.
    #[inline]
    pub fn has_async_pipeline(&self) -> bool {
        self.async_pipeline.is_some()
    }

    // -- Frame output accessors -------------------------------------------

    /// Tessellated vector meshes from the last update.
    #[inline]
    pub fn vector_meshes(&self) -> &[VectorMeshData] {
        &self.vector_meshes
    }

    /// 3D model instances from the last update.
    #[inline]
    pub fn model_instances(&self) -> &[ModelInstance] {
        &self.model_instances
    }

    /// Placed symbols from the last update.
    #[inline]
    pub fn placed_symbols(&self) -> &[PlacedSymbol] {
        &self.placed_symbols
    }

    /// Symbol asset dependency state for the last update.
    #[inline]
    pub fn symbol_assets(&self) -> &SymbolAssetRegistry {
        &self.symbol_assets
    }

    /// Look up feature state for a source-local feature id.
    pub fn feature_state(&self, source_id: &str, feature_id: &str) -> Option<&FeatureState> {
        self.feature_state.get(&FeatureStateId::new(source_id, feature_id))
    }

    /// Replace feature state for a source-local feature id.
    pub fn set_feature_state(
        &mut self,
        source_id: impl Into<String>,
        feature_id: impl Into<String>,
        state: FeatureState,
    ) {
        self.feature_state
            .insert(FeatureStateId::new(source_id, feature_id), state);
    }

    /// Set a single feature-state property.
    pub fn set_feature_state_property(
        &mut self,
        source_id: impl Into<String>,
        feature_id: impl Into<String>,
        key: impl Into<String>,
        value: crate::geometry::PropertyValue,
    ) {
        self.feature_state
            .entry(FeatureStateId::new(source_id, feature_id))
            .or_default()
            .insert(key.into(), value);
    }

    /// Remove feature state for a source-local feature id.
    pub fn remove_feature_state(&mut self, source_id: &str, feature_id: &str) -> Option<FeatureState> {
        self.feature_state.remove(&FeatureStateId::new(source_id, feature_id))
    }

    /// Clear all stored feature state.
    pub fn clear_feature_state(&mut self) {
        self.feature_state.clear();
    }

    /// Resolve a style layer's paint properties for a specific feature's
    /// current state.
    ///
    /// This is the primary convenience method for hover/selection restyling:
    /// it looks up the named style layer, retrieves the feature's current
    /// state from the internal store, and evaluates all paint properties
    /// through the [`StyleEvalContextFull`] path.
    ///
    /// Returns `None` when:
    /// - no style document is attached
    /// - the layer id does not exist in the style document
    /// - the layer type does not produce a [`VectorStyle`] (background,
    ///   hillshade, raster, model)
    ///
    /// # Example
    ///
    /// ```ignore
    /// map.set_feature_state_property("source", "feat-42", "hover", PropertyValue::Bool(true));
    /// if let Some(style) = map.resolve_feature_style("buildings", "source", "feat-42") {
    ///     // `style` has paint values resolved with hover=true.
    /// }
    /// ```
    pub fn resolve_feature_style(
        &self,
        style_layer_id: &str,
        source_id: &str,
        feature_id: &str,
    ) -> Option<VectorStyle> {
        use crate::style::StyleEvalContextFull;

        let document = self.style_document()?;
        let style_layer = document.layer(style_layer_id)?;
        let empty_state: FeatureState = HashMap::new();
        let state = self
            .feature_state
            .get(&FeatureStateId::new(source_id, feature_id))
            .unwrap_or(&empty_state);
        let ctx = StyleEvalContextFull::new(self.fractional_zoom() as f32, state);
        style_layer.resolve_style_with_feature_state(&ctx)
    }

    /// Attach an interaction manager for automatic hover/leave/click lifecycle.
    ///
    /// Once set, the host feeds raw pointer events into the manager (via
    /// [`interaction_manager_mut`](Self::interaction_manager_mut)) and drains
    /// high-level [`InteractionEvent`](crate::InteractionEvent)s each frame.
    pub fn set_interaction_manager(
        &mut self,
        manager: crate::interaction_manager::InteractionManager,
    ) {
        self.interaction_manager = Some(manager);
    }

    /// Remove the attached interaction manager, returning it if present.
    pub fn take_interaction_manager(
        &mut self,
    ) -> Option<crate::interaction_manager::InteractionManager> {
        self.interaction_manager.take()
    }

    /// Read-only access to the attached interaction manager.
    pub fn interaction_manager(&self) -> Option<&crate::interaction_manager::InteractionManager> {
        self.interaction_manager.as_ref()
    }

    /// Mutable access to the attached interaction manager.
    ///
    /// Use this to feed pointer events and drain emitted interaction events.
    pub fn interaction_manager_mut(
        &mut self,
    ) -> Option<&mut crate::interaction_manager::InteractionManager> {
        self.interaction_manager.as_mut()
    }

    // -- Event subscription (callback-based) ------------------------------

    /// Subscribe to interaction events of a given kind.
    ///
    /// Returns a [`ListenerId`](crate::event_emitter::ListenerId) for
    /// later removal via [`off`](Self::off).
    pub fn on<F>(
        &mut self,
        kind: crate::interaction::InteractionEventKind,
        callback: F,
    ) -> crate::event_emitter::ListenerId
    where
        F: Fn(&crate::interaction::InteractionEvent) + Send + Sync + 'static,
    {
        self.event_emitter.on(kind, callback)
    }

    /// Subscribe to a single occurrence of an interaction event kind.
    ///
    /// The listener is automatically removed after the first dispatch.
    pub fn once<F>(
        &mut self,
        kind: crate::interaction::InteractionEventKind,
        callback: F,
    ) -> crate::event_emitter::ListenerId
    where
        F: Fn(&crate::interaction::InteractionEvent) + Send + Sync + 'static,
    {
        self.event_emitter.once(kind, callback)
    }

    /// Unsubscribe a previously registered event listener.
    pub fn off(&mut self, id: crate::event_emitter::ListenerId) -> bool {
        self.event_emitter.off(id)
    }

    /// Dispatch interaction events to registered listeners.
    ///
    /// Call this after draining events from the interaction manager.
    /// Events are forwarded to all matching `on` / `once` callbacks.
    pub fn dispatch_events(&mut self, events: &[crate::interaction::InteractionEvent]) {
        self.event_emitter.dispatch(events);
    }

    /// Mutable access to the event emitter for advanced use cases.
    pub fn event_emitter_mut(&mut self) -> &mut crate::event_emitter::EventEmitter {
        &mut self.event_emitter
    }

    /// Invalidate placed-symbol tiles that depend on the given image id.
    pub fn invalidate_symbol_image_dependency(&mut self, image_id: &str) -> usize {
        self.invalidate_symbol_dependency_tiles(|deps| deps.images.contains(image_id))
    }

    /// Invalidate placed-symbol tiles that depend on the given glyph.
    pub fn invalidate_symbol_glyph_dependency(&mut self, font_stack: &str, codepoint: char) -> usize {
        let glyph = crate::symbols::GlyphKey {
            font_stack: font_stack.to_owned(),
            codepoint,
        };
        self.invalidate_symbol_dependency_tiles(|deps| deps.glyphs.contains(&glyph))
    }


    /// Override the vector meshes for this frame (useful for testing).
    pub fn set_vector_meshes(&mut self, meshes: Vec<VectorMeshData>) {
        let meshes = Arc::new(meshes);
        self.pending_vector_meshes = Some(meshes.clone());
        self.vector_meshes = meshes;
    }

    /// Override the model instances for this frame (useful for testing).
    pub fn set_model_instances(&mut self, instances: Vec<ModelInstance>) {
        let instances = Arc::new(instances);
        self.pending_model_instances = Some(instances.clone());
        self.model_instances = instances;
    }

    /// Override the placed symbols for this frame (useful for testing).
    pub fn set_placed_symbols(&mut self, symbols: Vec<PlacedSymbol>) {
        self.placed_symbols = Arc::new(symbols);
        self.symbol_assets.rebuild_from_symbols(&self.placed_symbols);
    }

    // =====================================================================
    // Update cycle
    // =====================================================================

    /// Recompute all derived state with an explicit delta-time (seconds).
    pub fn update_with_dt(&mut self, dt: f64) {
        let was_flying = self.animator.is_flying() || self.animator.is_easing();

        self.update_camera(dt);

        let is_flying = self.animator.is_flying() || self.animator.is_easing();

        // -- Async path: dispatch + poll (cheap every frame) ----------------
        if self.async_pipeline.is_some() {
            self.dispatch_data_requests();
            self.poll_completed_results(dt);
        } else {
            // -- Synchronous path (fallback) ---------------------------------
            //
            // Tile layer updates (poll completed HTTP responses, recompute
            // the visible tile set, issue new requests) are cheap and must
            // run every frame so that:
            //   1. Completed tile downloads are picked up promptly.
            //   2. The visible tile set tracks the current camera position.
            //   3. Tiles transition from "pending" to "loaded" without lag.
            //
            // Expensive work (terrain meshing, vector tessellation, symbol
            // placement, model collection) is throttled during animation.
            let animation_active = is_flying;

            // Always update tile layers every frame.
            self.update_tile_layers();

            if animation_active && self.data_update_interval > 0.0 {
                self.data_update_elapsed += dt;
                if self.data_update_elapsed >= self.data_update_interval {
                    self.data_update_elapsed = 0.0;
                    self.update_heavy_layers(dt);
                }
            } else {
                self.data_update_elapsed = 0.0;
                self.update_heavy_layers(dt);
            }
        }

        // Post-animation catch-up: ensure a full data update fires on the
        // first frame after a fly-to / ease-to animation finishes.
        if was_flying && !is_flying && self.async_pipeline.is_none() {
            self.update_tile_layers();
            self.update_heavy_layers(dt);
        }

        // -- Loading placeholders (lightweight, every frame) ----------------
        self.placeholder_time += dt;
        self.loading_placeholders = Arc::new(PlaceholderGenerator::generate(
            &self.visible_tiles,
            &self.placeholder_style,
            self.placeholder_time,
        ));

        if let Err(e) = self.sync_attached_style_runtime() {
            log::warn!("style sync error: {e:?}");
        }

        self.apply_pending_frame_overrides();

        // -- Recompute fog params for this frame ----------------------------
        {
            let bg = self.background_color().unwrap_or([1.0, 1.0, 1.0, 1.0]);
            let pitch = self.camera.pitch();
            let distance = self.camera.distance();
            let style_fog = self.style.as_ref()
                .and_then(|s| s.document().fog());
            let effective_fog = self.fog_config.as_ref().or(style_fog);
            self.computed_fog = crate::style::compute_fog(pitch, distance, bg, effective_fog);
        }
    }

    /// Forward an input event to the camera controller.
    ///
    /// [`Touch`](InputEvent::Touch) events are routed through the
    /// built-in [`GestureRecognizer`](crate::gesture::GestureRecognizer),
    /// which converts multi-touch sequences into pan / zoom / rotate
    /// events before forwarding them to the camera controller.
    pub fn handle_input(&mut self, event: InputEvent) {
        if let InputEvent::Touch(contact) = event {
            let derived = self.gesture_recognizer.process(contact);
            for e in derived {
                CameraController::handle_event(&mut self.camera, e, &self.constraints);
            }
            return;
        }
        CameraController::handle_event(&mut self.camera, event, &self.constraints);
    }

    /// Access the gesture recognizer (e.g. to call [`reset`](crate::gesture::GestureRecognizer::reset)).
    pub fn gesture_recognizer(&self) -> &crate::gesture::GestureRecognizer {
        &self.gesture_recognizer
    }

    /// Convenience: calls `update_with_dt(1.0 / 60.0)`.
    pub fn update(&mut self) {
        self.update_with_dt(1.0 / 60.0);
    }

    /// Begin a fly-to animation.
    pub fn fly_to(&mut self, options: crate::camera_animator::FlyToOptions) {
        self.animator.start_fly_to(&mut self.camera, &options);
    }

    /// Begin an ease-to animation.
    pub fn ease_to(&mut self, options: crate::camera_animator::EaseToOptions) {
        self.animator.start_ease_to(&mut self.camera, &options);
    }

    /// Immediately jump the camera to the given state.
    pub fn jump_to(
        &mut self,
        target: GeoCoord,
        distance: f64,
        pitch: Option<f64>,
        yaw: Option<f64>,
    ) {
        self.animator.cancel();
        self.camera.set_target(target);
        self.camera.set_distance(distance);
        if let Some(p) = pitch {
            self.camera.set_pitch(p);
        }
        if let Some(y) = yaw {
            self.camera.set_yaw(y);
        }
    }

    /// Tick the camera animator and recompute zoom / viewport / frustum.
    pub fn update_camera(&mut self, dt: f64) {
        self.animator.tick(&mut self.camera, dt);

        // Normalize the camera longitude after every animation tick to
        // keep it within [-180, 180).  Without this, fly-to and ease-to
        // animations that cross the antimeridian can leave the camera in
        // a different world copy, causing viewport_bounds and tile
        // selection to diverge and tiles to stop rendering.  This matches
        // the Mapbox/MapLibre wrap-jump handling behavior.
        {
            let target = *self.camera.target();
            let wrapped_lon = wrap_lon_180(target.lon);
            if (wrapped_lon - target.lon).abs() > 1e-12 {
                self.camera.set_target(GeoCoord::from_lat_lon(target.lat, wrapped_lon));
            }
        }

        let mpp = self.camera.meters_per_pixel();
        self.zoom_level = Self::mpp_to_zoom(mpp);
        self.viewport_bounds = self.compute_viewport_bounds();
        self.scene_viewport_bounds = self.compute_scene_viewport_bounds();
        self.frustum = Some(Frustum::from_view_projection(
            &self.camera.view_projection_matrix(),
        ));
        self.update_camera_motion_state(dt);

        let fractional_zoom = self.fractional_zoom();
        self.camera_zoom_delta = self
            .previous_fractional_zoom
            .map_or(0.0, |previous| fractional_zoom - previous);
        self.previous_fractional_zoom = Some(fractional_zoom);
    }


    /// Build a detached per-frame snapshot for renderers.
    pub fn frame_output(&self) -> FrameOutput {
        FrameOutput {
            view_projection: self.camera.view_projection_matrix(),
            frustum: self.frustum.clone(),
            tiles: Arc::clone(&self.visible_tiles),
            terrain: Arc::clone(&self.terrain_meshes),
            hillshade: Arc::clone(&self.hillshade_rasters),
            vectors: Arc::clone(&self.vector_meshes),
            models: Arc::clone(&self.model_instances),
            symbols: Arc::clone(&self.placed_symbols),
            visualization: Arc::clone(&self.visualization_overlays),
            placeholders: Arc::clone(&self.loading_placeholders),
            image_overlays: Arc::clone(&self.image_overlays),
            zoom_level: self.zoom_level,
        }
    }

    /// Query the terrain elevation at a geographic coordinate.
    pub fn elevation_at(&self, coord: &GeoCoord) -> Option<f64> {
        self.terrain.elevation_at(coord)
    }

    /// Unproject a screen pixel to a geographic coordinate (flat ground).
    pub fn screen_to_geo(&self, px: f64, py: f64) -> Option<GeoCoord> {
        self.camera.screen_to_geo(px, py)
    }

    /// Project a geographic coordinate to a screen-space pixel position.
    ///
    /// Returns `(px, py)` in logical pixels with `(0, 0)` at the
    /// top-left corner of the viewport, or `None` if the point is
    /// behind the camera.
    pub fn geo_to_screen(&self, geo: &GeoCoord) -> Option<(f64, f64)> {
        self.camera.geo_to_screen(geo)
    }

    /// Fit the camera to a geographic bounding box.
    ///
    /// Computes the center and zoom level that make the entire bounding
    /// box visible, accounting for optional padding.  Depending on
    /// `options.animate`, the transition may be animated (`fly_to`) or
    /// instant (`jump_to`).
    pub fn fit_bounds(&mut self, bounds: &GeoBounds, options: &FitBoundsOptions) {
        let center = bounds.center();

        // Project SW and NE to world meters.
        let sw_world = WebMercator::project_clamped(&bounds.sw());
        let ne_world = WebMercator::project_clamped(&bounds.ne());

        let dx = (ne_world.position.x - sw_world.position.x).abs();
        let dy = (ne_world.position.y - sw_world.position.y).abs();

        // Subtract padding from the effective viewport.
        let vw = (self.camera.viewport_width() as f64
            - options.padding.left
            - options.padding.right)
            .max(1.0);
        let vh = (self.camera.viewport_height() as f64
            - options.padding.top
            - options.padding.bottom)
            .max(1.0);

        // Meters-per-pixel required to fit the bounds.
        let mpp_x = dx / vw;
        let mpp_y = dy / vh;
        let mpp = mpp_x.max(mpp_y);

        // Convert mpp to zoom.
        let zoom = if mpp <= 0.0 || !mpp.is_finite() {
            MAX_ZOOM as f64
        } else {
            (WGS84_CIRCUMFERENCE / (mpp * TILE_PX))
                .log2()
                .clamp(0.0, MAX_ZOOM as f64)
        };

        // Clamp to max_zoom.
        let zoom = match options.max_zoom {
            Some(mz) => zoom.min(mz),
            None => zoom,
        };

        if options.animate {
            let fly = crate::camera_animator::FlyToOptions {
                center: Some(center),
                zoom: Some(zoom),
                bearing: options.bearing,
                pitch: options.pitch,
                duration: options.duration,
                ..Default::default()
            };
            self.fly_to(fly);
        } else {
            // Convert zoom to distance.
            let is_perspective = matches!(self.camera.mode(), CameraMode::Perspective);
            let distance = {
                let mpp = WGS84_CIRCUMFERENCE / (2.0_f64.powf(zoom) * TILE_PX);
                let vis_h = mpp * self.camera.viewport_height().max(1) as f64;
                if is_perspective {
                    vis_h / (2.0 * (self.camera.fov_y() / 2.0).tan())
                } else {
                    vis_h / 2.0
                }
            };
            self.jump_to(center, distance, options.pitch, options.bearing);
        }
    }

    /// Cast a ray and intersect with the flat ground plane (z = 0).
    pub fn ray_to_geo(&self, origin: glam::DVec3, direction: glam::DVec3) -> Option<GeoCoord> {
        if direction.z.abs() < 1e-12 {
            return None;
        }
        let t = -origin.z / direction.z;
        if t < 0.0 {
            return None;
        }
        let hit = origin + direction * t;
        let world = self.camera.target_world();
        let world_hit = WorldCoord::new(hit.x + world.x, hit.y + world.y, 0.0);
        Some(self.camera.projection().unproject(&world_hit))
    }

    /// Cast a ray and intersect with the terrain surface.
    ///
    /// Falls back to flat ground intersection if terrain is disabled or
    /// no intersection is found.
    pub fn ray_to_geo_on_terrain(
        &self,
        origin: glam::DVec3,
        direction: glam::DVec3,
    ) -> Option<GeoCoord> {
        if !self.terrain.enabled() {
            return self.ray_to_geo(origin, direction);
        }

        let world = self.camera.target_world();
        let steps = 64;
        let max_t = self.camera.distance() * 4.0;
        let step = max_t / steps as f64;

        let mut prev_above = true;
        for i in 0..=steps {
            let t = step * i as f64;
            let p = origin + direction * t;
            let world_hit = WorldCoord::new(p.x + world.x, p.y + world.y, p.z);
            let geo = self.camera.projection().unproject(&world_hit);
            let elev = self.terrain.elevation_at(&geo).unwrap_or(0.0);
            let above = p.z >= elev;
            if !above && prev_above && i > 0 {
                // Linear interpolation between previous and current step.
                let prev_t = step * (i - 1) as f64;
                let prev_p = origin + direction * prev_t;
                let prev_world = WorldCoord::new(prev_p.x + world.x, prev_p.y + world.y, prev_p.z);
                let prev_geo = self.camera.projection().unproject(&prev_world);
                let prev_elev = self.terrain.elevation_at(&prev_geo).unwrap_or(0.0);
                let prev_height = prev_p.z - prev_elev;
                let curr_height = p.z - elev;
                let frac = prev_height / (prev_height - curr_height);
                let hit_t = prev_t + (t - prev_t) * frac;
                let hit = origin + direction * hit_t;
                let hit_world = WorldCoord::new(hit.x + world.x, hit.y + world.y, hit.z);
                return Some(self.camera.projection().unproject(&hit_world));
            }
            prev_above = above;
        }
        // Fallback to flat ground.
        self.ray_to_geo(origin, direction)
    }

    /// Cast a ray and intersect with the flat ground plane, ignoring terrain.
    pub fn ray_to_flat_geo(&self, origin: glam::DVec3, direction: glam::DVec3) -> Option<GeoCoord> {
        self.ray_to_geo(origin, direction)
    }

    /// Screen-to-geo through the terrain surface.
    pub fn screen_to_geo_on_terrain(&self, px: f64, py: f64) -> Option<GeoCoord> {
        let (origin, direction) = self.camera.screen_to_ray(px, py);
        self.ray_to_geo_on_terrain(origin, direction)
    }

    // =====================================================================
    // Synchronous layer update (fallback when no async pipeline)
    // =====================================================================


    /// Full synchronous layer update (tile + heavy layers).
    ///
    /// Used by the non-animation path and the async dispatch path.
    // =====================================================================
    // Async dispatch + poll
    // =====================================================================


    // =====================================================================
    // Private helpers
    // =====================================================================

    /// Camera target in Web Mercator world coordinates.
    fn mercator_camera_world(&self) -> (f64, f64) {
        let w = WebMercator::project(self.camera.target());
        (w.position.x, w.position.y)
    }

    fn update_camera_motion_state(&mut self, dt: f64) {
        self.camera_motion_time_seconds += dt.max(0.0);

        let current_wrapped = self.mercator_camera_world();
        let current_target = if let Some(last) = self.camera_motion_samples.back() {
            glam::DVec2::new(
                last.target_world.x + heavy_layers::wrapped_world_delta(current_wrapped.0 - last.target_world.x),
                current_wrapped.1,
            )
        } else {
            glam::DVec2::new(current_wrapped.0, current_wrapped.1)
        };

        self.camera_motion_samples.push_back(CameraMotionSample {
            time_seconds: self.camera_motion_time_seconds,
            target_world: current_target,
        });
        self.trim_camera_motion_samples();
        self.recompute_camera_motion_state();
    }

    fn trim_camera_motion_samples(&mut self) {
        let max_samples = self.camera_velocity_config.sample_window.max(1) + 1;
        while self.camera_motion_samples.len() > max_samples {
            self.camera_motion_samples.pop_front();
        }
    }

    fn recompute_camera_motion_state(&mut self) {
        let pan_velocity_world = if let (Some(first), Some(last)) = (
            self.camera_motion_samples.front(),
            self.camera_motion_samples.back(),
        ) {
            let dt = last.time_seconds - first.time_seconds;
            if dt > 1e-9 {
                (last.target_world - first.target_world) / dt
            } else {
                glam::DVec2::ZERO
            }
        } else {
            glam::DVec2::ZERO
        };

        let current_wrapped = self.mercator_camera_world();
        let current_target_world = glam::DVec2::new(current_wrapped.0, current_wrapped.1);
        let look_ahead = self.camera_velocity_config.look_ahead_seconds.max(0.0);
        let predicted_delta = pan_velocity_world * look_ahead;

        self.camera_motion_state = CameraMotionState {
            pan_velocity_world,
            predicted_target_world: current_target_world + predicted_delta,
            predicted_viewport_bounds: heavy_layers::translated_world_bounds(&self.viewport_bounds, predicted_delta),
        };
    }

    /// Camera target in the active scene projection.
    /// Convert meters-per-pixel to an integer zoom level.
    fn mpp_to_zoom(mpp: f64) -> u8 {
        if mpp <= 0.0 || !mpp.is_finite() {
            return MAX_ZOOM;
        }
        let z = (WGS84_CIRCUMFERENCE / (mpp * TILE_PX)).log2();
        (z.round() as u8).min(MAX_ZOOM)
    }

    /// Compute the viewport bounding box in Web Mercator world coordinates.
    fn compute_viewport_bounds(&self) -> WorldBounds {
        use rustial_math::WebMercator;

        let w = self.camera.viewport_width() as f64;
        let h = self.camera.viewport_height() as f64;

        if w <= 0.0 || h <= 0.0 {
            let zero = WorldCoord::new(0.0, 0.0, 0.0);
            return WorldBounds::new(zero, zero);
        }

        let cam = &self.camera;

        // Check if camera supports orthographic bounds directly.
        if cam.mode() == CameraMode::Orthographic {
            let half_w = cam.distance() * (w / h).max(1.0);
            let half_h = cam.distance() / (w / h).min(1.0);
            let target = WebMercator::project(cam.target());
            let overscan = 1.3;
            return WorldBounds::new(
                WorldCoord::new(
                    target.position.x - half_w * overscan,
                    target.position.y - half_h * overscan,
                    0.0,
                ),
                WorldCoord::new(
                    target.position.x + half_w * overscan,
                    target.position.y + half_h * overscan,
                    0.0,
                ),
            );
        }

        let mut min_x = f64::MAX;
        let mut min_y = f64::MAX;
        let mut max_x = f64::MIN;
        let mut max_y = f64::MIN;
        let mut any_hit = false;

        for (sx, sy) in viewport_sample_points(w, h) {
            if let Some(geo) = cam.screen_to_geo(sx, sy) {
                let world = WebMercator::project_clamped(&geo);
                min_x = min_x.min(world.position.x);
                min_y = min_y.min(world.position.y);
                max_x = max_x.max(world.position.x);
                max_y = max_y.max(world.position.y);
                any_hit = true;
            }
        }

        if !any_hit {
            let target = WebMercator::project(cam.target());
            let mpp = cam.meters_per_pixel();
            let half_w = mpp * w * 0.5;
            let half_h = mpp * h * 0.5;
            return WorldBounds::new(
                WorldCoord::new(target.position.x - half_w, target.position.y - half_h, 0.0),
                WorldCoord::new(target.position.x + half_w, target.position.y + half_h, 0.0),
            );
        }

        let overscan = perspective_viewport_overscan(cam.pitch());
        let cx = (min_x + max_x) * 0.5;
        let cy = (min_y + max_y) * 0.5;
        let hw = (max_x - min_x) * 0.5 * overscan;
        let hh = (max_y - min_y) * 0.5 * overscan;
        WorldBounds::new(
            WorldCoord::new(cx - hw, cy - hh, 0.0),
            WorldCoord::new(cx + hw, cy + hh, 0.0),
        )
    }

    /// Compute the viewport bounding box in the active scene projection.
    fn compute_scene_viewport_bounds(&self) -> WorldBounds {
        let w = self.camera.viewport_width() as f64;
        let h = self.camera.viewport_height() as f64;

        if w <= 0.0 || h <= 0.0 {
            let zero = WorldCoord::new(0.0, 0.0, 0.0);
            return WorldBounds::new(zero, zero);
        }

        let cam = &self.camera;
        let proj = cam.projection();

        if cam.mode() == CameraMode::Orthographic {
            let half_w = cam.distance() * (w / h).max(1.0);
            let half_h = cam.distance() / (w / h).min(1.0);
            let target = proj.project(cam.target());
            let overscan = 1.3;
            return WorldBounds::new(
                WorldCoord::new(
                    target.position.x - half_w * overscan,
                    target.position.y - half_h * overscan,
                    0.0,
                ),
                WorldCoord::new(
                    target.position.x + half_w * overscan,
                    target.position.y + half_h * overscan,
                    0.0,
                ),
            );
        }

        let mut min_x = f64::MAX;
        let mut min_y = f64::MAX;
        let mut max_x = f64::MIN;
        let mut max_y = f64::MIN;
        let mut any_hit = false;

        for (sx, sy) in viewport_sample_points(w, h) {
            if let Some(geo) = cam.screen_to_geo(sx, sy) {
                let world = proj.project(&geo);
                min_x = min_x.min(world.position.x);
                min_y = min_y.min(world.position.y);
                max_x = max_x.max(world.position.x);
                max_y = max_y.max(world.position.y);
                any_hit = true;
            }
        }

        if !any_hit {
            let target = proj.project(cam.target());
            let mpp = cam.meters_per_pixel();
            let half_w = mpp * w * 0.5;
            let half_h = mpp * h * 0.5;
            return WorldBounds::new(
                WorldCoord::new(target.position.x - half_w, target.position.y - half_h, 0.0),
                WorldCoord::new(target.position.x + half_w, target.position.y + half_h, 0.0),
            );
        }

        let overscan = perspective_viewport_overscan(cam.pitch());
        let cx = (min_x + max_x) * 0.5;
        let cy = (min_y + max_y) * 0.5;
        let hw = (max_x - min_x) * 0.5 * overscan;
        let hh = (max_y - min_y) * 0.5 * overscan;
        WorldBounds::new(
            WorldCoord::new(cx - hw, cy - hh, 0.0),
            WorldCoord::new(cx + hw, cy + hh, 0.0),
        )
    }

    /// Re-evaluate the attached style runtime at the current zoom.
    fn sync_attached_style_runtime(&mut self) -> Result<(), StyleError> {
        // Currently a no-op: zoom-dependent style evaluation is not yet
        // wired into the layer stack.  The style document is applied once
        // at set_style() time.
        Ok(())
    }

    /// Replace an existing layer with the same name or push a new one.
    fn replace_or_push_named_layer(
        &mut self,
        name: &str,
        layer: Box<dyn crate::layer::Layer>,
    ) {
        if let Some(index) = self.layers.index_of(name) {
            let _ = self.layers.remove(index);
            self.layers.insert(index, layer);
        } else {
            self.layers.push(layer);
        }
        self.style = None;
    }


}


// =========================================================================
// Free helper functions
// =========================================================================