//! AzulMaps map widget. The P3 goal-app's central primitive.

//!

//! Architecture (per the user's design in MOBILE_SESSION_LOG and the

//! follow-up clarification):

//!

//! - **Widget, not a NodeType.** `MapWidget` builds a regular `<div>`

//!   that owns a `MapTileCache` `RefAny` dataset. The cache holds

//!   decoded SVG bytes per `MapTileId`; the dataset is the unit of

//!   persistence across relayout.

//! - **Tile cache survives relayout** via a `DatasetMergeCallback`.

//!   Every relayout creates a fresh `MapTileCache` skeleton; the

//!   merge callback transfers all `Ready` / `Pending` entries from

//!   the old dataset into the new one, so in-flight fetches and

//!   already-decoded SVGs aren't dropped.

//! - **VirtualView drives lazy rendering.** The widget's body is a

//!   `VirtualView` callback that:

//!     1. Computes which tile XYZs are visible from the current

//!        viewport + viewport size.

//!     2. For each visible tile not yet in the cache, marks it

//!        `Pending` and (eventually) enqueues an HTTP fetch.

//!     3. Returns a `Dom` whose children are one `<div>` per visible

//!        tile, GPU-translated into screen space via

//!        `transform: translate(x, y) scale(z)`. Each tile div's

//!        inner content is the cached SVG DOM, or an empty

//!        placeholder while the fetch is in flight.

//! - **MVT + MapCSS → SVG → DOM.** The decode pipeline (MVT protobuf

//!   bytes + a MapCSS stylesheet → an `<svg>` tree → the framework's

//!   existing svg-to-dom path) lands in a follow-up tick. This tick

//!   provides the widget shell + the dataset / merge-callback / virtual-

//!   view wiring; tiles render as empty placeholders.

//! - **Geolocation dot composes on top.** Users stack a normal child

//!   `Dom` (with a `NodeType::GeolocationProbe` deeper in the

//!   subtree) on top of the map widget — the widget doesn't bake in

//!   any geolocation feature itself.

//!

//! Compile gate: no new HTTP / MVT / proj4 dependencies in this tick.

//! Those land alongside the actual decode pipeline.

use alloc::collections::btree_map::BTreeMap;

use azul_core::callbacks::{

    VirtualViewCallback, VirtualViewCallbackInfo, VirtualViewReturn,

};

use azul_core::dom::{DatasetMergeCallbackType, Dom, OptionDom};

use azul_core::refany::{OptionRefAny, RefAny};

use azul_css::dynamic_selector::CssPropertyWithConditionsVec;

use azul_css::impl_option_inner; // for impl_widget_callback!'s impl_option!

use azul_css::AzString;

// ────────── POD types (api.json + codegen surface) ─────────────────────

/// Identity of one tile in a tiled-map XYZ scheme. Matches Leaflet /

/// OpenLayers / Mapbox conventions (Web Mercator, origin top-left).

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

#[repr(C)]

pub struct MapTileId {

    /// Zoom level. `0` = whole world in one tile, `~14` = street level

    /// for vector tiles, `~19` for raster.

    pub z: u8,

    /// Tile column at this zoom.

    pub x: u32,

    /// Tile row at this zoom.

    pub y: u32,

}

/// Configuration of one map tile layer — usually the base raster /

/// vector layer. Additional layers (heatmaps, custom GeoJSON) compose

/// as further `MapWidget` instances stacked atop.

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct MapTileLayer {

    /// `{z}` / `{x}` / `{y}` placeholders are substituted at fetch

    /// time. Matches Leaflet's `tileLayer(url_template)`.

    pub url_template: AzString,

    /// Minimum integer zoom this layer supports.

    pub min_zoom: u8,

    /// Maximum integer zoom this layer supports.

    pub max_zoom: u8,

    /// Attribution string the user MUST display (ODbL "© OpenStreetMap

    /// contributors" or similar). Most providers require it.

    pub attribution: AzString,

    /// MapCSS-style stylesheet driving per-layer fill / stroke /

    /// stroke-width. Empty = use the built-in default palette. Each

    /// rule is `selector { fill: …; stroke: …; stroke-width: …; }`

    /// where the selector's trailing token is matched against the MVT

    /// layer name (e.g. `water { fill: #9ecae1; }`, `.buildings { … }`).

    /// Parsed by `azul_dll::desktop::extra::map`'s tile decoder.

    pub style_css: AzString,

}

impl Default for MapTileLayer {

}

/// Centre + zoom + rotation state. The Leaflet shape

/// (`map.setView([lat, lon], zoom)`). `bearing_deg` + `pitch_deg` are

/// reserved for future 3D-camera work; most callers leave them at zero.

#[derive(Debug, Clone, Copy, PartialEq)]

#[repr(C)]

pub struct MapViewport {

    pub centre_lat_deg: f64,

    pub centre_lon_deg: f64,

    pub zoom: f32,

    pub bearing_deg: f32,

    pub pitch_deg: f32,

}

impl Default for MapViewport {

        // A neutral "whole world, slightly zoomed in" default. Apps

        // care will replace this immediately.

}

/// A geographic coordinate in degrees. Returned by

/// [`MapWidget::latlon_at_px`] and (P3) the map's `on_pin_tap` hook.

#[derive(Debug, Clone, Copy, PartialEq)]

#[repr(C)]

pub struct MapLatLon {

    pub lat_deg: f64,

    pub lon_deg: f64,

}

// ────────── MapWidget builder ──────────────────────────────────────────

// NOTE: `MapWidget` mirrors the api.json struct field-for-field so the

// codegen FFI transmute stays sound. Callback fields (e.g.

// `on_viewport_changed`) ARE allowed: codegen keeps `AzMapWidget` in sync

// (the Button / Camera pattern). The Rust-only tile-fetch worker stays in

// the FFI-opaque `MapTileCache` dataset (supplied via `dom_with_fetch`).

#[derive(Debug, Clone, PartialEq)]

#[repr(C)]

pub struct MapWidget {

    pub layer: MapTileLayer,

    pub viewport: MapViewport,

    pub container_style: CssPropertyWithConditionsVec,

    /// Optional hook fired when the user pans / zooms (effects / persist

    /// the viewport). FFI-exposed; re-set on each fresh build.

    pub on_viewport_changed: OptionMapViewportChanged,

    /// Optional hook fired when the user taps the map, with the tapped

    /// lat/lon. FFI-exposed; re-set on each fresh build.

    pub on_pin_tap: OptionMapPinTap,

}

impl MapWidget {

    /// Set a hook fired when the user pans / zooms the map. The map owns its

    /// own pan/pinch state; this lets your app observe or persist the

    /// resulting `MapViewport`. The backreference DI pattern (architecture.md).

    /// Builder form of [`set_on_viewport_changed`](Self::set_on_viewport_changed).

    /// Set a hook fired when the user taps the map (a press + release at ~the

    /// same point, no drag), with the tapped lat/lon. The backreference DI

    /// pattern (architecture.md).

    /// Builder form of [`set_on_pin_tap`](Self::set_on_pin_tap).

    /// Project a screen pixel `px` (relative to the map node's top-left, in a

    /// node of size `container`) to a lat/lon on the map at `viewport`. Small-

    /// angle Mercator (accurate at city zooms). Inverse of

    /// [`px_at_latlon`](Self::px_at_latlon). Exposed so apps don't reimplement

    /// the projection (e.g. to drop a pin where the user tapped).

    /// Inverse of [`latlon_at_px`](Self::latlon_at_px): where `coord` lands in

    /// container pixels at `viewport`.

    /// Construct the rendered `Dom`. The returned `Dom` is a single

    /// `<div>` with:

    /// - A `MapTileCache` `RefAny` dataset (initialised from this

    ///   widget's `viewport` + `layer`).

    /// - A `DatasetMergeCallback` so the cache survives relayout.

    /// - A `VirtualView` child that re-renders the visible-tile grid

    ///   on bounds change.

    /// - Mouse-down / mouse-move / mouse-up callbacks that pan the

    ///   viewport while a drag is active (the widget owns the

    ///   pan state via `MapTileCache::drag_anchor`, so user code

    ///   doesn't have to wire anything).

    /// - Pinch callbacks that zoom in / out.

    ///

    /// No tile-fetch worker is wired — tiles render as placeholders.

    /// Use [`dom_with_fetch`](Self::dom_with_fetch) to supply one.

    /// Like [`dom`](Self::dom), but wires a tile-fetch worker thread.

    /// `cb` runs on a framework `Thread` per visible tile: it reads the

    /// `TileFetchInit`, fetches + decodes, then

    /// `sender.send(ThreadReceiveMsg::WriteBack(...))` a `TileReadyMsg`

    /// targeting `map_tile_writeback`. The standard worker is

    /// `azul_dll::desktop::extra::map::tile_fetch_worker`; wrap it in a

    /// `ThreadCallback` to pass it here. See the recipe in

    /// `MOBILE_SESSION_LOG.md`.

        use azul_core::dom::{ComponentEventFilter, EventFilter, HoverEventFilter};

            // Fill the container (the Leaflet contract) via absolute inset:0 rather

            // than height:100%. A percentage height only resolves against a parent

            // with a DEFINITE height; the usual map container is a `flex-grow` item

            // whose height is not definite for percentage children, so height:100%

            // there resolves to INFINITY → the VirtualView gets infinite bounds and

            // positions every tile at y=∞ (off-screen → blank map). Absolute inset:0

            // instead sizes against the container's final, finite content box. The

            // container MUST be a positioned box (the demo's `position: relative`);

            // a non-empty `container_style` (via `with_container_style`) overrides.

            // AfterMount fires once when the widget first appears (and

            // again after a DOM-structure change re-mounts it). It's the

            // earliest point with a `CallbackInfo`, so we kick the

            // initial tile fetches here — without it the first frame's

            // tiles would stay `Pending` until the user panned/tapped.

            )

            )

            )

            )

            )

            )

            )

            )

            )

            // Native gesture events (UIPinchGestureRecognizer on iOS,

            // ScaleGestureDetector on Android, NSMagnificationGestureRecognizer

            // on macOS) — fire through the same map_on_pointer_move handler

            // which reads `info.get_pinch()` and applies the zoom delta.

            )

            )

                )

                // Fill the widget div with a PERCENTAGE box (not absolute). The

                // outer div above is absolutely sized, so its height IS definite —

                // height:100% here resolves against it (441px), giving the

                // VirtualView a finite box. (Absolute-against-absolute collapses to

                // 0 in the solver; percentage-against-a-definite-parent does not.)

            );

        // A caller-supplied container style replaces the default fill above

        // (`with_css_props` replaces the inline style) — the caller then owns sizing.

        } else {

        }

}

// ────────── Tile cache (dataset RefAny payload) ───────────────────────

#[derive(Debug)]

pub struct MapTileCache {

    pub layer: MapTileLayer,

    pub viewport: MapViewport,

    /// `Ready(svg)` once the tile has been fetched + decoded;

    /// `Pending` while queued, `Fetching` while a worker thread is

    /// in flight; absent otherwise. `BTreeMap` for deterministic

    /// iteration so the debug log + e2e snapshots are stable.

    pub tiles: BTreeMap<MapTileId, TileEntry>,

    /// Worker thread entry point that fetches + decodes one tile.

    /// Supplied by `MapWidget::dom_with_fetch` (the caller, usually

    /// `azul_dll`'s map-tiles glue, provides this because the MVT

    /// decoder lives in `azul-dll`, which `azul-layout` can't depend

    /// on). `None` means "no fetch wired": tiles stay `Pending` and

    /// the placeholder grid renders. The merge callback carries this

    /// across relayout. Held as the `ThreadCallback` wrapper (not the

    /// raw fn pointer) so it round-trips through the FFI codegen.

    pub fetch_callback: Option<crate::thread::ThreadCallback>,

    /// Pixel coordinates of the cursor at the last mouse-down /

    /// touch-down on the widget. `Some` while a drag is in flight,

    /// `None` between drags. The framework consults this on every

    /// mouse-move to derive the pixel delta, which then converts to a

    /// lat/lon delta via the Web Mercator inverse.

    pub drag_anchor: Option<azul_core::geom::LogicalPosition>,

    /// Pinch reference distance (pixels) — the two-finger separation

    /// the last time a pinch event was observed for this widget.

    /// `Some` while a pinch is in flight, `None` between gestures.

    /// On each subsequent pinch update we compute

    /// `dz = log2(current_distance / pinch_anchor)` and add it to

    /// `viewport.zoom`, then reset the anchor to the current

    /// distance — so the gesture stays continuous across many frames.

    pub pinch_anchor: Option<f32>,

    /// The user's `on_viewport_changed` hook, copied here from the builder

    /// so the pan / pinch callbacks can fire it. Carried across relayout.

    pub on_viewport_changed: OptionMapViewportChanged,

    /// Pixel position of the last pointer-down (the original press point, not

    /// overwritten by pan moves). Used to tell a tap from a drag in pointer-up.

    pub press_origin: Option<azul_core::geom::LogicalPosition>,

    /// The user's `on_pin_tap` hook, copied from the builder so pointer-up can

    /// fire it. Carried across relayout.

    pub on_pin_tap: OptionMapPinTap,

}

impl MapTileCache {

    /// Worker-thread → main-thread write path. Set the decoded SVG for

    /// a tile (called from `map_tile_writeback`). Stamps `Ready`.

    /// Mark a tile's fetch as failed so the grid doesn't re-spawn it

    /// every frame.

    /// Bound the tile cache by evicting tiles far from the current viewport.

    ///

    /// Without this, `tiles` grows without limit — panning across the world or

    /// zooming in and out keeps every tile ever fetched (each decoded SVG is

    /// tens-to-hundreds of KB), so a long session leaks memory. Called after a

    /// viewport change once the new view's tiles are queued.

    ///

    /// Eviction is viewport-distance based (the right policy for spatial data,

    /// stronger than plain LRU): each tile is scored by zoom mismatch + squared

    /// distance from the viewport centre (projected into the current zoom's tile

    /// space), and the farthest are dropped first. IN-FLIGHT tiles

    /// (`Pending`/`Fetching`) are never evicted (their worker would write into a

    /// gone entry), and on-screen tiles score near-zero so they survive.

        const MAX_CACHED_TILES: usize = 192;

        // Higher score = evict sooner.

            // Project the tile's centre into the CURRENT zoom's tile space so

            // distances across zoom levels are comparable.

        // Farthest first.

        }

}

#[derive(Debug, Clone)]

pub enum TileEntry {

    /// Needed by the viewport, fetch not yet spawned.

    Pending,

    /// A worker thread is fetching / decoding this tile right now.

    /// Distinct from `Pending` so the spawn pass doesn't double-fire.

    Fetching,

    /// Tile decoded into an SVG document. Held as the raw SVG

    /// string for now; the VirtualView callback will feed it

    /// through the framework's svg-to-dom pipeline on the next

    /// re-render.

    Ready { svg: AzString },

    /// Fetch failed. Held so the framework doesn't immediately

    /// re-try the same URL — caller can choose to clear failed

    /// entries on retry.

    Failed { error: AzString },

}

/// Worker-thread input: which tile to fetch, the resolved URL, and the

/// MapCSS stylesheet to apply when converting features to SVG. Boxed

/// into the `Thread::create` init `RefAny`.

#[derive(Debug, Clone)]

pub struct TileFetchInit {

    pub tile: MapTileId,

    pub url: AzString,

    /// Copy of `MapTileLayer::style_css` (empty = default palette).

    pub style_css: AzString,

}

/// Worker-thread output, sent back via `ThreadWriteBackMsg`. The

/// `map_tile_writeback` callback downcasts to this and stamps the

/// cache.

#[derive(Debug, Clone)]

pub struct TileReadyMsg {

    pub tile: MapTileId,

    /// Decoded SVG document for the tile, or empty on failure (with

    /// `error` set).

    pub svg: AzString,

    /// Empty on success; an error message on failure.

    pub error: AzString,

}

// ────────── Merge callback — cache survives relayout ─────────────────

/// Copy every entry from the previous frame's cache into the new

/// frame's cache. The next layout pass thus sees the same in-flight /

/// decoded set without re-fetching anything.

    // SHARE the previous cache across the relayout — do NOT copy its tiles into

    // the freshly-built one. The tile-fetch worker threads each hold a clone of

    // THIS very `RefAny` (handed to them at spawn time); returning it keeps their

    // writebacks landing in the same cache the VirtualView reads. The reconcile

    // pass re-points the VirtualView node's `refany` at this returned dataset

    // (core::diff::transfer_states), so the pure content callback reads it too.

    //

    // The old behaviour returned a fresh `new_data` with the old tiles *copied*

    // in. That orphaned the workers' clone after the first relayout: every tile

    // arriving later was written into the old, no-longer-rendered cache, so the

    // map stayed blank. Returning the persistent (old) cache fixes it at the root

    // — workers, dataset and VirtualView all reference one underlying allocation.

    //

    // The freshly-built `new_data` carries the layout-callback-controlled

    // CONFIG: the fetch worker the `.dom()` shim wired, and — critically — the

    // viewport/layer the app passed to `with_viewport()` / `create()` for THIS

    // build. Adopt those into the persistent cache: app callbacks (zoom

    // buttons, Recentre, Locate) mutate app state and return RefreshDom, and

    // the merge previously discarded that new viewport ("viewport intact"),

    // so external viewport changes never took effect — only the widget's

    // internal drag/wheel (which mutate the persistent cache directly)

    // worked. Widget-internal changes stay consistent because every build's

    // `with_viewport()` receives the app state, which the on_viewport_changed

    // hook keeps in sync with internal pans/zooms.

    {

    }

// ────────── Pan + zoom callbacks ─────────────────────────────────────

use crate::callbacks::CallbackInfo;

use azul_core::callbacks::Update;

use azul_core::callbacks::TimerCallbackReturn;

use azul_core::task::{Duration, SystemTimeDiff, TerminateTimer, TimerId};

use crate::timer::{Timer, TimerCallback, TimerCallbackInfo};

// --- User hook: on_viewport_changed (backreference DI, FFI-exposed) ---

/// User hook fired when the user pans or zooms the map. Lets app code observe

/// or persist the widget-driven `MapViewport` (which otherwise lives only in

/// the opaque `MapTileCache`). The backreference DI pattern (architecture.md).

pub type MapViewportChangedCallbackType =

    extern "C" fn(RefAny, CallbackInfo, MapViewport) -> Update;

impl_widget_callback!(

    MapViewportChanged,

    OptionMapViewportChanged,

    MapViewportChangedCallback,

    MapViewportChangedCallbackType

);

azul_core::impl_managed_callback! {

    wrapper:        MapViewportChangedCallback,

    info_ty:        CallbackInfo,

    return_ty:      Update,

    default_ret:    Update::DoNothing,

    invoker_static: MAP_VIEWPORT_CHANGED_INVOKER,

    invoker_ty:     AzMapViewportChangedCallbackInvoker,

    thunk_fn:       az_map_viewport_changed_callback_thunk,

    setter_fn:      AzApp_setMapViewportChangedCallbackInvoker,

    from_handle_fn: AzMapViewportChangedCallback_createFromHostHandle,

    extra_args:     [ viewport: MapViewport ],

}

/// Invoke a map widget's optional `on_viewport_changed` hook with the new

/// viewport, returning the user's `Update` (`DoNothing` if no hook is set).

        }

    }

// --- User hook: on_pin_tap (backreference DI, FFI-exposed) ---

/// User hook fired when the user taps the map (a press + release at ~the same

/// point, no pan/pinch). Receives the tapped [`MapLatLon`] (projected via

/// [`MapWidget::latlon_at_px`]) so apps can drop a pin without wiring their own

/// tap handling + projection. The backreference DI pattern (architecture.md).

pub type MapPinTapCallbackType = extern "C" fn(RefAny, CallbackInfo, MapLatLon) -> Update;

impl_widget_callback!(

    MapPinTap,

    OptionMapPinTap,

    MapPinTapCallback,

    MapPinTapCallbackType

);

azul_core::impl_managed_callback! {

    wrapper:        MapPinTapCallback,

    info_ty:        CallbackInfo,

    return_ty:      Update,

    default_ret:    Update::DoNothing,

    invoker_static: MAP_PIN_TAP_INVOKER,

    invoker_ty:     AzMapPinTapCallbackInvoker,

    thunk_fn:       az_map_pin_tap_callback_thunk,

    setter_fn:      AzApp_setMapPinTapCallbackInvoker,

    from_handle_fn: AzMapPinTapCallback_createFromHostHandle,

    extra_args:     [ coord: MapLatLon ],

}

/// Invoke a map widget's optional `on_pin_tap` hook with the tapped coordinate.

    }

/// Pointer down → record the drag anchor. The widget knows nothing

/// about the user's overall state RefAny — only its own dataset —

/// so the anchor lives in `MapTileCache::drag_anchor`.

    #[cfg(feature = "std")]

    };

/// Pointer move during an active drag → translate the pixel delta

/// into a lat/lon delta via the Web Mercator inverse and update

/// `viewport.centre_lat_deg / centre_lon_deg`. Updates the anchor so

/// the next move computes a fresh delta.

///

/// If a pinch gesture is in flight (two fingers on the widget), the

/// pan branch is skipped and the move event drives zoom instead —

/// `dz = log2(current_distance / pinch_anchor)`. The next move resets

/// the anchor to the current distance so the gesture stays

/// continuous across many frames.

    #[cfg(feature = "std")]

    // Active pinch wins over single-finger pan.

        };

        // Pinch is exclusive with pan — clear the drag anchor so the

        // pinch end doesn't accidentally drop into a pan.

        // Re-render the VirtualView in place so the new zoom's tiles compute

        // immediately, without a DOM rebuild. (See map_tile_writeback for why

        // RefreshDom is avoided.)

    };

    };

    };

    // Pan moved the viewport — re-render the VirtualView in place so the newly

    // visible tiles are computed (and marked Pending) right away. No RefreshDom.

/// Pointer up / pointer leave → end the drag *and* the pinch. Either

/// can be in flight (and pinch supersedes pan in the move handler);

/// clear both anchors on release.

    // Cursor + container size for tap projection (read before borrowing data).

        }

    };

    // A press + release at ~the same point (no pan/pinch) is a tap: project it

    // to lat/lon and fire the user's on_pin_tap hook.

    // After a pan / pinch settles, kick off fetches for any tiles the new

    // viewport needs. (Only a `CallbackInfo`-bearing callback can spawn them.)

    // Re-render in place so Fetching/Ready states show as tiles arrive. The

    // worker writebacks will trigger further re-renders themselves. No RefreshDom.

/// Mouse-wheel / trackpad scroll over the map = ZOOM (Leaflet / Google-Maps

/// convention), not content scroll. The map's VirtualView has no scroll overflow,

/// so the framework's queued wheel deltas would otherwise be wasted — drain them

/// and apply as a zoom step, then queue + spawn the tiles the new zoom needs and

/// re-render in place.

    // Wheel delta that triggered this Scroll callback (sign = direction). The map

    // is not a scroll container, so this comes from the per-pass wheel delta, not

    // the scroll-physics input queue (which only feeds scrollable nodes).

        }

    };

    #[cfg(feature = "std")]

    // The grid's on-screen rect is the widget size (needed to recompute the tiles

    // the new zoom needs).

        };

        // ~0.5 zoom levels per wheel notch. X11 delivers wheel-up as dy > 0;

        // wheel-up zooms IN, wheel-down zooms OUT (Leaflet / Google-Maps).

    };

    // `rem_euclid` (not `%`) so even large negative deltas normalise:

    // `%` follows the dividend's sign and would leak values < -180.

// ────────── Web-Mercator (WGS-84 ↔ XYZ tile space) ───────────────────

//

// `tile_count` is `2^zoom`. Tile-space x grows east (0 at lon -180,

// `tile_count` at lon +180); y grows south (0 at the north edge

// ~85.05°, `tile_count` at the south edge). These four functions are

// exact inverses of each other and are the single source of truth for

// the widget's projection — `map_widget_render` forward-projects the

// viewport centre through them; tap-to-pin will inverse-project taps.

/// Longitude (deg) → fractional tile-x at the given `tile_count`.

/// Latitude (deg) → fractional tile-y at the given `tile_count`.

/// Fractional tile-x → longitude (deg). Inverse of [`lon_to_tile_x`].

/// Verified against the forward direction in the tests below; the

/// upcoming tap-to-pin handler reuses it to turn a tap into a lat/lon.

#[allow(dead_code)]

/// Fractional tile-y → latitude (deg). Inverse of [`lat_to_tile_y`].

#[allow(dead_code)]

/// Apply a drag of `(dx_px, dy_px)` screen pixels to a viewport centre,

/// returning the new `(centre_lon_deg, centre_lat_deg)`. Dragging right

/// (+dx) pans the map content right, i.e. recentres on a *lower* longitude

/// (hence the minus). Latitude uses the small-angle Mercator approximation

/// (`d_lat ≈ dy·cos(lat)·360/world`), accurate to a few metres at city

/// zooms; the exact inverse only matters for very long drags near the

/// poles. Longitude wraps to [-180, 180); latitude clamps to the

/// Web-Mercator ±85.05° limit. The shared, unit-tested core of

/// `map_on_pointer_move`.

    // World pixels at the current fractional zoom (256 px / tile).

/// Parse a standalone `<svg>…</svg>` string into a `Dom` subtree via

/// the framework's existing XML→DOM path. The SVG is wrapped in a

/// minimal `<html><body>` envelope because `str_to_dom_unstyled`

/// expects a document root; the wrapper divs are zero-impact in

/// layout. Returns `None` if the `xml` feature is off or parsing

/// fails — the caller then falls back to the placeholder glyph.

// Render the decoded tile SVG to a COLOUR image node, reusing the framework's

// `render_svg_group` rasteriser (the one that renders the tiger), which honours

// the SVG `fill`/`stroke` attrs that `features_to_svg` emits. The DOM SVG path

// (`str_to_dom_unstyled` → `SvgNodeData::Path`) only produces a clip mask, so it

// cannot paint the feature colours — hence the tiles rendered grey.

#[cfg(all(feature = "xml", feature = "cpurender"))]

#[cfg(all(feature = "xml", not(feature = "cpurender")))]

pub fn svg_string_to_dom(svg: &str) -> Option<Dom> {

    use azul_core::xml::{str_to_dom_unstyled, ComponentMap};

    let wrapped = alloc::format!("<html><body>{}</body></html>", svg);

    let nodes = crate::xml::parse_xml_string(&wrapped).ok()?;

    let component_map = ComponentMap::default();

    str_to_dom_unstyled(nodes.as_ref(), &component_map).ok()

}

#[cfg(not(feature = "xml"))]

fn svg_string_to_dom(_svg: &str) -> Option<Dom> {

    None

}

/// Fires once when the widget first mounts. Kicks the initial tile

/// fetches so the map populates without waiting for a user gesture.

/// (The VirtualView marks the viewport's tiles `Pending` during the

/// layout pass that precedes mount-event dispatch; this handler then

/// spawns the workers for them.) Returns `RefreshDom` so the

/// `Fetching` state shows immediately.

    #[cfg(feature = "std")]

    // Install a low-frequency sweep timer. Pointer/scroll/after_mount spawn

    // fetches directly, but a viewport change that originates from a *rebuild*

    // (an app's zoom/recentre button → with_viewport) marks new tiles `Pending`

    // in the VirtualView render, which has no `add_thread` — so without this

    // sweep the map would sit grey after a button-zoom until the next

    // drag/wheel. The timer's cache clone tracks the persistent dataset

    // `transfer_states` keeps across rebuilds, so it stays unified.

    )

    // Re-render the VirtualView IN PLACE (not RefreshDom). RefreshDom would

    // rebuild the DOM, allocate a fresh MapTileCache, and orphan the clone of

    // the cache we just handed the worker threads — their tiles would then write

    // to a cache nobody renders. The dataset is shared via the construction-time

    // RefAny::clone(), so re-invoking in place lets the workers' writes land in

    // the same cache the VirtualView reads.

/// Scan the cache for `Pending` tiles and spawn one framework `Thread`

/// per tile (capped per call so a big viewport jump doesn't spawn

/// hundreds at once). Each thread gets:

/// - init `RefAny` = `TileFetchInit { tile, url }`

/// - writeback `RefAny` = a clone of the cache dataset, so

///   `map_tile_writeback` mutates the same cache the VirtualView reads.

///

/// Tiles transition `Pending → Fetching` here so they aren't

/// re-spawned next frame. No-op when the cache has no `fetch_callback`.

    use crate::thread::Thread;

    use azul_core::task::ThreadId;

    // Per-call spawn cap — bounds the burst on a big viewport jump.

    const MAX_SPAWN_PER_CALL: usize = 16;

    // Collect the work first (URL build + state flip) under one borrow,

    // then spawn outside it so we don't hold the cache lock across

    // `info.add_thread`.

    {

        };

        // Now that the current view's tiles are queued (Fetching, so eviction

        // protects them), bound the cache by dropping tiles far from the

        // viewport — otherwise panning/zooming grows it without limit.

    }

        };

        }

    };

    #[cfg(feature = "std")]

    #[cfg(feature = "std")]

/// Low-frequency timer that spawns fetches for any `Pending` tiles the

/// VirtualView marked since the last spawn — the path that the

/// pointer/scroll/after_mount handlers can't cover (a rebuild-driven viewport

/// change marks tiles `Pending` in the VirtualView render, which has no

/// `add_thread`). Installed once in `map_on_after_mount`. The `data` clone

/// tracks the persistent dataset, so writebacks land in the rendered cache.

/// Cheap no-op when nothing is `Pending`; never `RefreshDom`s (that would

/// orphan the cache the workers write to — tile writebacks drive re-render).

/// `{z}/{x}/{y}` substitution. Mirrors `azul_dll`'s `build_tile_url`

/// (the widget can't reach the dll, so it's duplicated here — trivial).

    use alloc::string::ToString;

/// Worker-thread → main-thread writeback. `cache_dataset` is the

/// `writeback_data` handed to `Thread::create` (the same

/// `MapTileCache` the widget reads); `incoming` is the `TileReadyMsg`

/// the worker sent. Stamps the tile `Ready` (or `Failed`) and asks for

/// a relayout so the VirtualView renders the new content.

    };

    {

        };

        #[cfg(feature = "std")]

    } // drop the cache borrow before touching `info`

    // Re-render the VirtualView(s) IN PLACE so the pure content callback re-reads

    // the shared cache we just mutated. NOT `RefreshDom`: a DOM rebuild would

    // allocate a fresh `MapTileCache` and orphan THIS worker's clone of it (the

    // VirtualView's `refany`, the node dataset and the worker's writeback handle

    // are all clones of one `RefAny` — same underlying data — only while the DOM

    // is not rebuilt). Re-invoking in place keeps that share intact, so this tile

    // and every later one reach the rendered view.

/// Inclusive `(x_min, x_max, y_min, y_max)` tile range covering a

/// `width_px × height_px` viewport centred at tile-space `(centre_x,

/// centre_y)`, at fractional `zoom_scale` and integer `tile_count` (2^z).

/// A one-tile margin (`+ 1.0`) is added each side so a tile scrolling into

/// view is already requested; the result is clamped to the valid

/// `0..=tile_count-1` grid. The pure core of `map_widget_render`'s grid

/// loop — what decides which tiles get fetched.

    // x is NOT clamped: the map wraps horizontally. Callers take the tile id mod

    // `tile_count` (so a column past the antimeridian shows the far side of the

    // world) while positioning the div at the un-wrapped column — seamless pan

    // across ±180° with no empty gutter. y IS clamped: there is no data beyond

    // the Web-Mercator poles, so vertical over-scan must not request bogus rows.

/// Wrap a (possibly negative or over-range) tile column into the valid

/// `0..tile_count` band — the horizontal world-wrap. `rem_euclid` (not `%`)

/// so columns west of the antimeridian map to the east side: at `tile_count`

/// = 4, column `-1` → `3`, column `4` → `0`.

/// `f(view)` — the tile ids a `viewport` needs to fill a `bounds`-sized widget.

/// Shared by the VirtualView render and the pan/zoom handlers so a handler can

/// mark + spawn the NEW viewport's tiles immediately, rather than waiting for the

/// next render pass to discover them. Mirrors `map_widget_render`'s grid math.

    }

// ────────── VirtualView callback — visible-tile rendering ─────────────

    // Defensive: if the widget was placed in a container that gives it no definite

    // size, the bounds come through as 0 or non-finite. Computing a tile grid then

    // positions tiles at NaN/∞ (off-screen → blank) and can allocate unboundedly, so

    // render nothing until the layout settles to a finite box.

        None => {

        }

    };

    // Round the requested fractional zoom down to the nearest integer

    // tile zoom the layer supports.

    // Convert WGS-84 → Web-Mercator-XYZ tile-space via the shared

    // projection helpers (the single source of truth, unit-tested below).