Module map 

Map widget — MVT tile + MapCSS → SVG → DOM (AzulMaps goal app, P3). Cache lives in a dataset RefAny owned by a merge callback so it survives relayout. See layout/src/widgets/map.rs for the design. 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.

Structs

MapLatLon

A geographic coordinate in degrees. Returned by MapWidget::latlon_at_px and (P3) the map’s on_pin_tap hook.

MapPinTap

MapPinTapCallback

MapTileCache

MapTileId

Identity of one tile in a tiled-map XYZ scheme. Matches Leaflet / OpenLayers / Mapbox conventions (Web Mercator, origin top-left).

MapTileLayer

Configuration of one map tile layer — usually the base raster / vector layer. Additional layers (heatmaps, custom GeoJSON) compose as further MapWidget instances stacked atop.

MapViewport

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.

MapViewportChanged

MapViewportChangedCallback

MapWidget

TileFetchInit

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.

TileReadyMsg

Worker-thread output, sent back via ThreadWriteBackMsg. The map_tile_writeback callback downcasts to this and stamps the cache.

Enums

OptionMapPinTap

OptionMapViewportChanged

TileEntry

Statics

MAP_PIN_TAP_INVOKER

Process-global slot for this callback kind’s host-side invoker.

MAP_VIEWPORT_CHANGED_INVOKER

Process-global slot for this callback kind’s host-side invoker.

Functions

AzApp_setMapPinTapCallbackInvoker

Register the host-side invoker for this callback kind.

AzApp_setMapViewportChangedCallbackInvoker

Register the host-side invoker for this callback kind.

AzMapPinTapCallback_createFromHostHandle

C-ABI export wrapping <Wrapper>::create_from_host_handle.

AzMapViewportChangedCallback_createFromHostHandle

C-ABI export wrapping <Wrapper>::create_from_host_handle.

map_tile_writeback

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.

Type Aliases

AzMapPinTapCallbackInvoker

Pointer-arg variant of this callback kind’s typedef.

AzMapViewportChangedCallbackInvoker

Pointer-arg variant of this callback kind’s typedef.

MapPinTapCallbackType

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).

MapViewportChangedCallbackType

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).