Map script design and migration
This page describes the design frozen on 2026-10-10. The new module and APIs are still being implemented; this is not a released API reference. See the existing script API for executable usage and developer APIs for platform coverage.
A shared map script
New scripts will import map, gis, and expr from the built-in sqsmap module. Web, desktop, and mobile hosts will expose the same map interface. Applications supply map initialization and their own windows or pages.
Map methods follow MapLibre conventions, including addSource/addLayer, setPaintProperty/setLayoutProperty, flyTo/fitBounds, and on/off/once. The existing gis module, resource references, and task return behavior remain compatible through an adapter.
Results and events
| Call | Design contract |
|---|---|
| Map mutations | Methods returning the map in the reference retain chaining; submission and application are distinct |
| ready / flush / sync extensions | Wait for initialization, application of a captured command watermark, or a fresh applied-state snapshot |
| on | Returns a cancellable subscription |
| off | Returns the map |
| once with a listener | Returns the map |
| once without a listener | Returns a Promise for the event |
| Rendered/source feature and elevation queries | Use await on all three platforms; differences from synchronous reference queries are explicit |
| GeoJSON updates and cluster queries | Follow the Promise contract of the frozen MapLibre 6.13.0 reference |
Explicit interactive sessions retain listeners after initialization and clean them up on stop or map destruction. One-shot scripts retain their existing completion behavior. Command application, resource readiness, rendering, and animation completion are separate states.
Custom tools and actual support
Applications draw their own layer panels, scale displays, zoom buttons, north reset, and 2D/3D tools. The map exposes state, operations, and events. North reset and restoring a top-down view are separate; view mode and globe projection are also distinct.
Each capability will state availability, parameter limits, backend requirements, and verification status. Missing web adapters or mobile execution chains remain implementation work. Platform declarations cannot replace acceptance evidence. Hosts document DOM, fullscreen, location, and native texture differences.
The reference is pinned to MapLibre GL JS 6.13.0. Mappings, declarations, and runnable examples will be updated alongside each implemented API, with planned and available interfaces clearly distinguished.
06.3 implementation revision: camera and coordinate queries return promises on all script hosts; use await for authoritative applied state. Chained writes and explicit flush retain the common syntax. Other planned methods remain subject to actual capabilities.