@mapmap/maps 0.8.0 → 0.10.0

package/README.md

@@ -333,6 +333,24 @@ small custom images, each with an optional label. They are placed in
 Studio's Markers tab, so a designer can ship "here are our depots" with the
 style itself - no places data, no code change:
 
+> **Glyph markers now render without this SDK.** A published theme's glyph
+> pins and dots are compiled INTO its `style.json` - an inline
+> `mm-user-markers` GeoJSON source plus two symbol layers over MapMap's SDF
+> marker sprite - so they draw in **any** MapLibre client that loads the
+> style URL: `new maplibregl.Map({ style })`, MapLibre Native on iOS and
+> Android, static/server-side renderers. No `MapMapMap`, no `MarkersLayer`,
+> no code at all.
+>
+> The one exception is a marker with a custom **`image`** (`data:` URI):
+> a static sprite cannot carry per-theme artwork, so the compiler skips
+> those items rather than drawing the wrong glyph in their place. They
+> render only through `MarkersLayer`, below.
+>
+> You still want `MarkersLayer` to **change** markers at runtime, to draw
+> custom-image markers, or for short-text numbered pins. Use
+> `hasBakedMarkers(map)` to find out whether the current style is already
+> drawing its own.
+
 ```ts
 import { MarkersLayer, markersFromThemeUrl } from "@mapmap/maps";
 
@@ -392,6 +410,16 @@ layer.destroy();           // clear() + detach the style.load listener
   style that INCLUDES runtime sources/layers, so a diffed `setStyle`
   removes `mm-user-markers` and the `style.load` that `setState` fires
   afterwards is what puts it back.
+- **Against a baked style it takes over, it does not double-draw.** A style
+  compiled from a theme with markers already carries `mm-user-markers` plus
+  a second layer, `mm-user-markers-glyph`, that this SDK never creates.
+  When you give a `MarkersLayer` markers on such a style, it removes both
+  baked layers and installs its own - so the markers appear exactly once,
+  and custom-image and short-text pins (which the baked layers cannot
+  carry) work as they always have. A `MarkersLayer` you construct and never
+  hand markers to leaves the baked layers completely alone, so the style
+  keeps drawing them. `hasBakedMarkers(map)` reports whether the current
+  style is baked; `BAKED_MARKERS_GLYPH_ID` is the layer id it looks for.
 
 ### `class NavigationCamera`
 
@@ -474,9 +502,15 @@ const map = new MapMapMap({
   below.
 - **`extra.markers`** (Studio's custom markers & labels, schema v1) rides
   the same way: `{ "version": 1, "items": [ { "id", "lng", "lat", "icon",
-  "colour", "size", "label", "image" } ] }`, up to 200 items, never part of
-  the compiled `style.json`. Read it with `markersFromTheme(theme)` /
-  `markersFromThemeUrl(url)` and draw it with `MarkersLayer` (above).
+  "colour", "size", "label", "image" } ] }`, up to 200 items. The raw block
+  is never copied into `style.json`, but it IS compiled into it: every
+  glyph marker becomes an `mm-user-markers` GeoJSON source plus the
+  `mm-user-markers` / `mm-user-markers-glyph` symbol layers over the SDF
+  marker sprite (the style's `sprite` is set to it unless the theme names
+  its own), so the markers render from the style URL alone in any MapLibre
+  client. Markers with a custom `image` are the exception - they are left
+  out of the bake and drawn only by `MarkersLayer`. Read the block with
+  `markersFromTheme(theme)` / `markersFromThemeUrl(url)`.
   `extra` as a whole is bounded at 256 KB serialised, and each marker
   `image` at 64 KB decoded - the per-image caps multiply, so a few
   full-size marker images will hit the block cap first.
@@ -772,8 +806,16 @@ Neither the mark nor the attribution can be switched off:
   `attributionControl: { customAttribution: "© Your Co" }` adds your own
   credit alongside the OSM one.
 
-In a bottom corner the mark sits above the attribution: MapLibre prepends
-controls in the bottom corners, so the control added last is the highest.
+The default layout is the canonical one: OpenStreetMap attribution in
+small print bottom-left, the MapMap mark bottom-right. Pass
+`attributionPosition: "bottom-right" | "bottom-left" | "top-left" |
+"top-right"` to `createMap` to mount the credit in another corner; there
+is no need to dig the control out of the map's internals to move it. The
+two are never in the same corner, because stacking the mark on the credit
+makes a line the ODbL requires unreadable. The SDK enforces that: if the
+attribution's corner and the mark's corner collide (via
+`attributionPosition`, `logo.position` or both), the mark moves to the
+opposite bottom corner and one `console.warn` is logged for that map.
 
 ## Turn-by-turn guidance
 
@@ -922,3 +964,18 @@ npm test            # vitest (pure-logic unit tests, no browser)
 
 Proprietary - © 2026 Mapmap AI Ltd, distributed under a commercial licence.
 See [`LICENSE`](./LICENSE).
+
+## 3D terrain
+
+```ts
+createMap({ container: "map", terrain: true });
+createMap({ container: "map", terrain: { exaggeration: 1.4, hillshade: true } });
+map.setTerrain(false);
+```
+
+The default DEM is the same dataset the gateway samples for `POST
+/elevation`, so rendered terrain and elevation queries agree. The SDK
+re-applies terrain across style swaps, gives hillshade its own DEM source
+(sharing one causes artefacts) and carries the DEM attribution. Note that
+terrain displaces by ABSOLUTE elevation: custom layers drawing in a local
+frame must add `map.queryTerrainElevation(...)` at their anchor.

package/dist/index.d.ts

@@ -1,6 +1,77 @@
-import maplibregl, { CustomLayerInterface, Map, StyleSpecification, MapOptions, ExpressionSpecification } from 'maplibre-gl';
+import maplibregl, { Map, CustomLayerInterface, StyleSpecification, MapOptions, ExpressionSpecification } from 'maplibre-gl';
 export { DirectionIconName, DirectionIconStep, directionIconSvg, directionIcons, iconNameForManeuver, iconNameForStep, iconNamesForSteps } from './direction-icons.js';
 
+/**
+ * 3D terrain and hillshading for MapMap maps.
+ *
+ * MapLibre can displace the ground by a DEM and shade it, but only if a
+ * `raster-dem` source is present and re-applied after every style load.
+ * This module owns that lifecycle so `new MapMapMap({ terrain: true })` is
+ * all a caller needs.
+ *
+ * Six things this encodes, each of which cost real debugging time building
+ * the survey viewer:
+ *
+ * 1. Terrain displaces by ABSOLUTE elevation. `queryTerrainElevation`
+ *    returns absolute metres, so custom layers drawing in a local frame
+ *    must add the terrain height at the map centre — otherwise every
+ *    distance-derived effect is computed from a camera underground.
+ * 2. Terrain does not survive `setStyle`. The source and the `setTerrain`
+ *    call must both be re-applied on every `style.load`.
+ * 3. A `hillshade` layer must NOT share the source used by `setTerrain` —
+ *    sharing one produces artefacts. Two sources, same tiles.
+ * 4. The DEM needs its own attribution; it is not covered by the OSM
+ *    credit the vector tiles carry.
+ * 5. Sky needs an explicit `atmosphere-blend`: MapLibre's default ramps to
+ *    zero at low zoom, so the sky silently stops drawing and the container
+ *    background shows through as a band across the horizon.
+ * 6. `fog-ground-blend` is where fog STARTS (0 = at the camera), not where
+ *    it ends. A low value paints a fog slab over the ground the moment the
+ *    camera looks toward the horizon.
+ */
+
+/** Terrain configuration. `true` means "on, with sensible defaults". */
+interface TerrainOptions {
+    /**
+     * Vertical exaggeration. 1 is true-to-life; 1.2–1.5 reads better on
+     * gentle terrain. Clamped to 0–8.
+     */
+    exaggeration?: number;
+    /**
+     * DEM tile template. Defaults to the Mapzen terrarium set on AWS Open
+     * Data — the same dataset the MapMap gateway reports as
+     * `mapzen-terrain-tiles` from `POST /elevation`, so a map and an
+     * elevation query agree with each other.
+     *
+     * Self-hosters: point this at your own terrarium tiles.
+     */
+    url?: string;
+    /** Encoding of the DEM tiles. Defaults to `"terrarium"`. */
+    encoding?: "terrarium" | "mapbox";
+    /** Max zoom of the DEM tile set. Defaults to 15. */
+    maxzoom?: number;
+    /** Tile size in px. Defaults to 256. */
+    tileSize?: number;
+    /** Attribution for the DEM. Defaults to the Mapzen/AWS credit. */
+    attribution?: string;
+    /**
+     * Add a `hillshade` layer as well, for relief shading that reads even
+     * with the camera pointing straight down. Uses its own source (see 3).
+     */
+    hillshade?: boolean;
+}
+declare const DEFAULT_TERRAIN_URL = "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png";
+declare const DEFAULT_TERRAIN_ATTRIBUTION: string;
+/** Normalise `true | TerrainOptions` into a full, clamped config. */
+declare function resolveTerrain(input: boolean | TerrainOptions | undefined): Required<Omit<TerrainOptions, "hillshade">> & {
+    hillshade: boolean;
+} | null;
+type ResolvedTerrain = NonNullable<ReturnType<typeof resolveTerrain>>;
+/** Add the sources/layers and switch terrain on. Safe to call repeatedly. */
+declare function applyTerrain(map: Map, cfg: ResolvedTerrain): void;
+/** Turn terrain off and remove what {@link applyTerrain} added. */
+declare function removeTerrain(map: Map): void;
+
 /**
  * Shared public types for @mapmap/maps.
  *
@@ -273,13 +344,14 @@ type LogoPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left";
 /** Options for {@link LogoControl}. */
 interface LogoOptions {
     /**
-     * Corner to render in. Default `bottom-right`.
-     *
-     * In a bottom corner the mark sits ABOVE the attribution, despite being
-     * added after it: MapLibre prepends controls in the bottom corners
-     * (`insertBefore(container.firstChild)`) and the corner is anchored to
-     * the bottom edge, so the control added last is the one that ends up
-     * highest. Verified against maplibre-gl 5's `addControl`.
+     * Corner to render in. Default `bottom-right` — the opposite corner
+     * from the attribution, which the SDK mounts bottom-left (movable with
+     * `attributionPosition`). That is the canonical MapMap layout:
+     * attribution small bottom-left, mark bottom-right, never both in one
+     * corner (stacking the mark on the OSM credit makes a licence-required
+     * line unreadable). {@link MapMapMap} enforces that: if this corner is
+     * the attribution's corner, the mark is mounted in the opposite bottom
+     * corner instead, with one `console.warn` for that map.
      */
     position?: LogoPosition;
     /** Link target when clicked. Default the MapMap site. */
@@ -1052,10 +1124,12 @@ declare function applyPoiDesign(map: PoiPaintMap, design: PoiDesign, fallbackTex
  * their own bundled maplibre-gl copy) but still want to read MapMap PMTiles.
  */
 declare function registerPmtilesProtocol(gl?: typeof maplibregl): void;
+/** Map corners an enforced control (attribution, mark) can be mounted in. */
+type AttributionPosition = "bottom-left" | "bottom-right" | "top-left" | "top-right";
 interface MapMapOptions {
     /**
      * The MapMap wordmark on the map (like the Google Maps / Mapbox marks).
-     * Always on, at bottom-right above the attribution by default; pass
+     * Always on, at bottom-right (the attribution's opposite corner); pass
      * `{ position, href }` to move or relink it.
      *
      * The mark cannot be taken off. Every displayed MapMap map carries it,
@@ -1087,6 +1161,15 @@ interface MapMapOptions {
     center?: [number, number];
     /** Initial zoom. Defaults to `5`. */
     zoom?: number;
+    /**
+     * 3D terrain from a DEM. `true` uses sensible defaults; pass
+     * {@link TerrainOptions} to set exaggeration, point at your own DEM
+     * tiles, or add relief shading.
+     *
+     * The default DEM is the same dataset the gateway reports from
+     * `POST /elevation`, so a map and an elevation query agree.
+     */
+    terrain?: boolean | TerrainOptions;
     /**
      * Extra MapLibre `MapOptions` merged last (escape hatch for hash, bearing,
      * maxBounds, etc.). `container` and `style` here are ignored.
@@ -1099,6 +1182,22 @@ interface MapMapOptions {
      * served under, for MapMap and for you.
      */
     mapOptions?: Partial<Omit<MapOptions, "container" | "style">>;
+    /**
+     * Corner for the OpenStreetMap attribution. Default `"bottom-left"`,
+     * which is the canonical MapMap layout: attribution small bottom-left,
+     * MapMap mark bottom-right. This chooses the credit's corner and nothing
+     * else; the credit itself stays on regardless (see
+     * `mapOptions.attributionControl` above), so there is no longer any
+     * reason to reach into `map._controls` to relocate it.
+     *
+     * The attribution and the mark never share a corner: stacking the mark
+     * on the credit makes a line the ODbL requires unreadable. If the corner
+     * requested here is the mark's corner (whether the mark's default
+     * bottom-right or an explicit `logo.position`), the mark moves to the
+     * opposite bottom corner and the SDK logs one `console.warn` for that
+     * map.
+     */
+    attributionPosition?: AttributionPosition;
 }
 /** Options for {@link MapMapMap.setRouteEffect}. */
 interface SetRouteEffectOptions extends RouteFlowOptions {
@@ -1138,6 +1237,8 @@ declare class MapMapMap {
     private effectLayer;
     /** True while an effect re-apply is already queued behind the style. */
     private effectWaiting;
+    /** Resolved terrain config, or null when terrain is off. */
+    private terrainConfig;
     private destroyed;
     private readonly pendingWaits;
     private readonly notices;
@@ -1162,6 +1263,12 @@ declare class MapMapMap {
      * and the listeners detach as soon as one fires (or on `destroy()`).
      */
     private whenStyleReady;
+    private readonly handleStyleLoadForTerrain;
+    /**
+     * Turn terrain on or off after construction. `false` removes the DEM
+     * sources and any hillshade layer this SDK added.
+     */
+    setTerrain(terrain: boolean | TerrainOptions): void;
     private readonly handleStyleLoadForEffects;
     /** The current style's `metadata`, if it can be read yet. */
     private styleMetadata;
@@ -1292,6 +1399,18 @@ declare const MARKER_GLYPH_VIEWBOX = 24;
  * gateway's Rust validator. Do not change ids, defaults or key formats
  * here without coordinating all three.
  *
+ * BAKED STYLES. Since the SDF marker sprite shipped, the theme compiler
+ * TRANSLATES a theme's `extra.markers` block into the same `mm-user-markers`
+ * source plus two sprite-driven symbol layers, so a published style URL
+ * draws its glyph markers in ANY MapLibre client — native SDKs and static
+ * renderers included — with no SDK code running at all. This layer is still
+ * a strict superset (runtime changes, custom `data:` images, short-text
+ * numbered pins), so when it is given markers on a style that is already
+ * baked it TAKES OVER: it removes the two baked layers and installs its
+ * own, rather than drawing a second copy. Constructing one and never
+ * setting markers leaves a baked style untouched. See
+ * {@link hasBakedMarkers}.
+ *
  * Like PlacesLayer, the layer survives `setStyle` (theme swaps) — but NOT
  * because a diffed `setStyle` leaves it alone. `Style.serialize()` includes
  * runtime-added sources and layers, so MapLibre's diff sees
@@ -1330,6 +1449,25 @@ declare const MAX_MARKER_LABEL_LENGTH = 120;
 declare const MAX_MARKER_TEXT_LENGTH = 3;
 /** The shared GeoJSON source id AND symbol layer id (contract). */
 declare const MARKERS_ID = "mm-user-markers";
+/**
+ * The SECOND symbol layer a BAKED style carries — the glyph-and-label layer
+ * the theme compiler appends next to `mm-user-markers` when it translates
+ * `extra.markers` into style constructs (`sn_style::MARKERS_GLYPH_LAYER_ID`).
+ *
+ * This layer is the reliable "already baked" signal: {@link MarkersLayer}
+ * never creates it, so finding it means the style itself is drawing the
+ * markers and a naive install would draw them TWICE.
+ */
+declare const BAKED_MARKERS_GLYPH_ID = "mm-user-markers-glyph";
+/**
+ * Whether the map's current style carries compiler-baked marker layers —
+ * i.e. its markers already render in any MapLibre client, with no SDK code.
+ *
+ * Useful for deciding whether to construct a {@link MarkersLayer} at all:
+ * you only need one to CHANGE the markers at runtime, or to render the
+ * custom `data:` image markers a static sprite cannot carry.
+ */
+declare function hasBakedMarkers(map: MapMapMap | Map): boolean;
 /** One parsed marker of an `extra.markers` v1 block. */
 interface MarkerItem {
     /** Stable unique id, non-empty, at most 64 characters. */
@@ -1581,6 +1719,24 @@ declare class MarkersLayer {
      * install as well as every data rebuild.
      */
     private registerImages;
+    /**
+     * TAKE OVER from a baked style. A style compiled from a theme with an
+     * `extra.markers` block already draws those markers itself, from an
+     * inline GeoJSON source plus two sprite-driven symbol layers — so
+     * installing on top would draw every marker twice, and pointing the SDK's
+     * feature shape at the baked layers would draw nothing sensible (they
+     * read `bodySize`/`anchor`, this layer writes `iconImage`/`iconSize`).
+     *
+     * Take-over rather than no-op, because this layer is a strict superset:
+     * it also renders the custom `data:` image markers and the short-text
+     * numbered pins that a static sprite cannot carry. The baked SOURCE is
+     * kept and its data replaced in place; only the two baked LAYERS go.
+     *
+     * Only ever runs once markers have been set on this layer, so a
+     * `new MarkersLayer(map)` that is never given any leaves a baked style
+     * completely alone. Idempotent; returns whether anything was taken over.
+     */
+    private takeOverBakedLayers;
     /** Add-or-update the images, source and layer on the current style. */
     private install;
     /**
@@ -3598,4 +3754,4 @@ declare class VoiceGuidance {
     private playEarcon;
 }
 
-export { ALERT_CONTRAST_MIN, AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type AlertChipContent, type AlertContrastIssue, type AlertPresentation, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraAlert, CameraAlertChip, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, type EndpointMarker, type EndpointsDesign, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, type MapDisplayMode, MapMapMap, type MapMapOptions, type MapMapTheme, type MarkerGlyphId, type MarkerItem, type MarkerSize, type MarkersBlock, MarkersLayer, type MarkersLayerIds, type MarkersLayerOptions, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, type NavAlertAudioMode, type NavAlertChipPosition, type NavAlertIconSet, type NavAlertKindDesign, type NavAlertLeadDistance, type NavAlertMode, type NavAlertSound, type NavAlertsDesign, type NavBannerDesign, type NavCameraDesign, type NavCameraKind, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, type PlacesLabelOptions, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, type PositionPuckOptions, type ProbeUploadOutcome, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RenderMarkerImageOptions, type RenderedMarkerImage, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerIds, type RouteLayerOptions, type RouteLineStyle, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, renderMarkerImage, resetDiagnostics, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };
+export { ALERT_CONTRAST_MIN, AdrCheck, type AdrCheckOptions, type AdrCheckRequest, type AdrCheckResult, type AdrDimensions, type AdrTunnelCategory, type AlertChipContent, type AlertContrastIssue, type AlertPresentation, type AttributionPosition, BAKED_MARKERS_GLYPH_ID, type BannerComponent, type BannerContent, type BannerInstruction, type BuildStyleOptions, type CameraAlert, CameraAlertChip, type CameraFix, DEFAULT_GLYPHS_URL, DEFAULT_TERRAIN_ATTRIBUTION, DEFAULT_TERRAIN_URL, DEFAULT_TERRITORY_TILES_URL, type DiagnosticIssue, EFFECTS_METADATA_KEY, type EndpointMarker, type EndpointsDesign, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, type FlythroughController, type FlythroughOptions, type FlythroughPose, GuidanceBanner, type GuidanceSeverity, type GuidanceSpokenPrompt, type IsochroneFeatureCollection, IsochroneLayer, type IsochroneLayerOptions, LOGO_SVG, type LaneIndication, type LayerOverride, type LngLatLike, LogoControl, type LogoOptions, type LogoPosition, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, type MapDiagnosticsInput, type MapDisplayMode, MapMapMap, type MapMapOptions, type MapMapTheme, type MarkerGlyphId, type MarkerItem, type MarkerSize, type MarkersBlock, MarkersLayer, type MarkersLayerIds, type MarkersLayerOptions, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, type NavAlertAudioMode, type NavAlertChipPosition, type NavAlertIconSet, type NavAlertKindDesign, type NavAlertLeadDistance, type NavAlertMode, type NavAlertSound, type NavAlertsDesign, type NavBannerDesign, type NavCameraDesign, type NavCameraKind, type NavDesign, type NavPuckDesign, type NavRouteDesign, NavigationCamera, type NavigationCameraMode, type NavigationCameraOptions, type NearestByDriveTimeOptions, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, type ParsedRoute, type Place, type PlacePointFeature, type PlaceWithDistance, type PlaceWithDriveTime, type PlacesFeatureCollection, type PlacesIcon, type PlacesInput, type PlacesLabelOptions, PlacesLayer, type PlacesLayerIds, type PlacesLayerOptions, type PlacesSelectOptions, type PoiCategoryDesign, type PoiDesign, PositionPuck, type PositionPuckOptions, type ProbeUploadOutcome, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, type ReachabilityMode, type RenderMarkerImageOptions, type RenderedMarkerImage, type RibbonMesh, type RouteEffectLayer, type RouteEffectName, type RouteFlowOptions, type RouteGeometry, RouteLayer, type RouteLayerIds, type RouteLayerOptions, type RouteLineStyle, type RouteOptions, type RouteProfile, SIGNAL_BLUE, SOURCE_LAYERS, type SetRouteEffectOptions, type SeverityProsody, type ShowReachabilityOptions, type SpeakOptions, type StepGuidance, type SunTimes, type TerrainOptions, type Theme, type ThemeEffects, ThemeScheduler, type ThemeSchedulerOptions, type TruckParams, type UploadProbeOptions, VoiceGuidance, type VoiceGuidanceOptions, type VoiceGuidanceUpdate, type VoiceInstruction, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, applyTerrain, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, hasBakedMarkers, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, removeTerrain, renderMarkerImage, resetDiagnostics, resolveTerrain, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };

package/dist/index.js

@@ -104,6 +104,72 @@ function watchForAuthFailures(map, apiKey) {
   }
 }
 
+// src/terrain.ts
+var DEFAULT_TERRAIN_URL = "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png";
+var DEFAULT_TERRAIN_ATTRIBUTION = '<a href="https://registry.opendata.aws/terrain-tiles/">Terrain data</a> Mapzen, AWS Open Data';
+var TERRAIN_SOURCE_ID = "mapmap-terrain-dem";
+var HILLSHADE_SOURCE_ID = "mapmap-hillshade-dem";
+var HILLSHADE_LAYER_ID = "mapmap-hillshade";
+var MAX_EXAGGERATION = 8;
+function resolveTerrain(input) {
+  if (!input) return null;
+  const o = input === true ? {} : input;
+  const raw = o.exaggeration ?? 1;
+  return {
+    // NaN must not reach MapLibre: it silently flattens the whole terrain.
+    exaggeration: Number.isFinite(raw) ? Math.min(MAX_EXAGGERATION, Math.max(0, raw)) : 1,
+    url: o.url ?? DEFAULT_TERRAIN_URL,
+    encoding: o.encoding ?? "terrarium",
+    maxzoom: o.maxzoom ?? 15,
+    tileSize: o.tileSize ?? 256,
+    attribution: o.attribution ?? DEFAULT_TERRAIN_ATTRIBUTION,
+    hillshade: o.hillshade ?? false
+  };
+}
+function applyTerrain(map, cfg) {
+  const demSpec = {
+    type: "raster-dem",
+    tiles: [cfg.url],
+    encoding: cfg.encoding,
+    tileSize: cfg.tileSize,
+    maxzoom: cfg.maxzoom,
+    attribution: cfg.attribution
+  };
+  if (!map.getSource(TERRAIN_SOURCE_ID)) {
+    map.addSource(TERRAIN_SOURCE_ID, demSpec);
+  }
+  map.setTerrain({ source: TERRAIN_SOURCE_ID, exaggeration: cfg.exaggeration });
+  if (!cfg.hillshade) {
+    if (map.getLayer(HILLSHADE_LAYER_ID)) map.removeLayer(HILLSHADE_LAYER_ID);
+    return;
+  }
+  if (!map.getSource(HILLSHADE_SOURCE_ID)) {
+    map.addSource(HILLSHADE_SOURCE_ID, demSpec);
+  }
+  if (!map.getLayer(HILLSHADE_LAYER_ID)) {
+    const layers = map.getStyle()?.layers ?? [];
+    const firstLineOrSymbol = layers.find(
+      (l) => l.type === "line" || l.type === "symbol"
+    );
+    map.addLayer(
+      {
+        id: HILLSHADE_LAYER_ID,
+        type: "hillshade",
+        source: HILLSHADE_SOURCE_ID,
+        paint: { "hillshade-exaggeration": 0.5 }
+      },
+      firstLineOrSymbol?.id
+    );
+  }
+}
+function removeTerrain(map) {
+  map.setTerrain(null);
+  if (map.getLayer(HILLSHADE_LAYER_ID)) map.removeLayer(HILLSHADE_LAYER_ID);
+  for (const id of [TERRAIN_SOURCE_ID, HILLSHADE_SOURCE_ID]) {
+    if (map.getSource(id)) map.removeSource(id);
+  }
+}
+
 // src/coords.ts
 function toLngLat(point) {
   if (Array.isArray(point)) {
@@ -1887,6 +1953,8 @@ var MapMapMap = class {
     this.effectExplicit = false;
     /** True while an effect re-apply is already queued behind the style. */
     this.effectWaiting = false;
+    /** Resolved terrain config, or null when terrain is off. */
+    this.terrainConfig = null;
     // Lifecycle: `destroy()` must silence anything still queued behind a
     // style load, and the cleanups let it detach those listeners.
     this.destroyed = false;
@@ -1897,6 +1965,10 @@ var MapMapMap = class {
     // removal is its own licence problem and deserves its own line, but a
     // theme swap or re-render must never repeat one.
     this.notices = /* @__PURE__ */ new Set();
+    this.handleStyleLoadForTerrain = () => {
+      if (this.destroyed || !this.terrainConfig) return;
+      applyTerrain(this.map, this.terrainConfig);
+    };
     this.handleStyleLoadForEffects = () => {
       if (this.destroyed) return;
       if (!this.effectExplicit) {
@@ -1931,8 +2003,21 @@ var MapMapMap = class {
       center: options.center ?? DEFAULT_CENTER,
       zoom: options.zoom ?? DEFAULT_ZOOM,
       ...options.mapOptions,
-      attributionControl
+      // Never let the constructor mount the attribution: it would land in
+      // MapLibre's default corner, bottom-RIGHT, which is the mark's
+      // corner. The canonical MapMap layout (Matt, 4 Aug 2026) is
+      // attribution small bottom-LEFT, mark bottom-RIGHT, never stacked —
+      // an SDK map must produce that with zero configuration, because
+      // every embed that got the old both-bottom-right default shipped
+      // the mark sitting on top of the OSM credit, and one demo "fixed"
+      // that by display:none-ing the credit, which is an ODbL breach.
+      attributionControl: false
     });
+    const attributionPosition = options.attributionPosition ?? "bottom-left";
+    this.map.addControl(
+      new maplibregl.AttributionControl(attributionControl),
+      attributionPosition
+    );
     if (options.logo === false) {
       this.notice(
         "logo-removal",
@@ -1940,11 +2025,23 @@ var MapMapMap = class {
       );
     }
     const logoOptions = typeof options.logo === "object" && options.logo !== null ? options.logo : {};
-    this.map.addControl(
-      new LogoControl(logoOptions),
-      logoOptions.position ?? "bottom-right"
-    );
+    let logoPosition = logoOptions.position ?? "bottom-right";
+    if (logoPosition === attributionPosition) {
+      logoPosition = attributionPosition.endsWith("left") ? "bottom-right" : "bottom-left";
+      this.notice(
+        "logo-collision",
+        `the MapMap mark and the attribution cannot share the ${attributionPosition} corner (the mark would cover the OpenStreetMap credit, which the ODbL requires readable). The mark has moved to ${logoPosition}.`
+      );
+    }
+    this.map.addControl(new LogoControl(logoOptions), logoPosition);
     this.map.on("style.load", this.handleStyleLoadForEffects);
+    this.terrainConfig = resolveTerrain(options.terrain);
+    this.map.on("style.load", this.handleStyleLoadForTerrain);
+    if (this.terrainConfig) {
+      this.whenStyleReady(() => {
+        if (this.terrainConfig) applyTerrain(this.map, this.terrainConfig);
+      });
+    }
     runMapDiagnostics({
       container: options.container,
       map: this.map,
@@ -1994,6 +2091,19 @@ var MapMapMap = class {
     this.pendingWaits.add(cleanup);
     for (const event of events) this.map.on(event, run);
   }
+  /**
+   * Turn terrain on or off after construction. `false` removes the DEM
+   * sources and any hillshade layer this SDK added.
+   */
+  setTerrain(terrain) {
+    if (this.destroyed) return;
+    this.terrainConfig = resolveTerrain(terrain);
+    const cfg = this.terrainConfig;
+    this.whenStyleReady(() => {
+      if (cfg) applyTerrain(this.map, cfg);
+      else removeTerrain(this.map);
+    });
+  }
   /** The current style's `metadata`, if it can be read yet. */
   styleMetadata() {
     try {
@@ -2342,6 +2452,11 @@ var MAX_MARKER_ID_LENGTH = 64;
 var MAX_MARKER_LABEL_LENGTH = 120;
 var MAX_MARKER_TEXT_LENGTH = 3;
 var MARKERS_ID = "mm-user-markers";
+var BAKED_MARKERS_GLYPH_ID = "mm-user-markers-glyph";
+function hasBakedMarkers(map) {
+  const ml = map instanceof MapMapMap ? map.map : map;
+  return ml.getLayer(BAKED_MARKERS_GLYPH_ID) !== void 0;
+}
 var MARKER_IMAGE_MIME = /^data:image\/(png|jpeg|webp|svg\+xml);base64,/;
 function isRecord3(v) {
   return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -2596,11 +2711,12 @@ var MarkersLayer = class {
       type: "FeatureCollection",
       features: this.items.map((item) => this.featureFor(item))
     };
+    const tookOver = this.takeOverBakedLayers();
     const source = this.map.getSource(MARKERS_ID);
-    if (source) {
+    if (source && !tookOver) {
       this.registerImages();
       source.setData(this.data);
-    } else if (this.map.isStyleLoaded()) {
+    } else if (tookOver || this.map.isStyleLoaded()) {
       this.install();
     }
   }
@@ -2703,9 +2819,33 @@ var MarkersLayer = class {
     }
     for (const key of needed) this.registeredImageKeys.add(key);
   }
+  /**
+   * TAKE OVER from a baked style. A style compiled from a theme with an
+   * `extra.markers` block already draws those markers itself, from an
+   * inline GeoJSON source plus two sprite-driven symbol layers — so
+   * installing on top would draw every marker twice, and pointing the SDK's
+   * feature shape at the baked layers would draw nothing sensible (they
+   * read `bodySize`/`anchor`, this layer writes `iconImage`/`iconSize`).
+   *
+   * Take-over rather than no-op, because this layer is a strict superset:
+   * it also renders the custom `data:` image markers and the short-text
+   * numbered pins that a static sprite cannot carry. The baked SOURCE is
+   * kept and its data replaced in place; only the two baked LAYERS go.
+   *
+   * Only ever runs once markers have been set on this layer, so a
+   * `new MarkersLayer(map)` that is never given any leaves a baked style
+   * completely alone. Idempotent; returns whether anything was taken over.
+   */
+  takeOverBakedLayers() {
+    if (this.map.getLayer(BAKED_MARKERS_GLYPH_ID) === void 0) return false;
+    this.map.removeLayer(BAKED_MARKERS_GLYPH_ID);
+    if (this.map.getLayer(MARKERS_ID)) this.map.removeLayer(MARKERS_ID);
+    return true;
+  }
   /** Add-or-update the images, source and layer on the current style. */
   install() {
     if (!this.data) return;
+    this.takeOverBakedLayers();
     this.registerImages();
     const existing = this.map.getSource(MARKERS_ID);
     if (existing) {
@@ -5719,6 +5859,6 @@ function clampVolume(volume) {
   return Math.min(1, Math.max(0, volume));
 }
 
-export { ALERT_CONTRAST_MIN, AdrCheck, CameraAlertChip, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, GuidanceBanner, IsochroneLayer, LOGO_SVG, LogoControl, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, MapMapMap, MarkersLayer, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, NavigationCamera, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, PlacesLayer, PositionPuck, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, RouteLayer, SIGNAL_BLUE, SOURCE_LAYERS, ThemeScheduler, VoiceGuidance, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, renderMarkerImage, resetDiagnostics, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };
+export { ALERT_CONTRAST_MIN, AdrCheck, BAKED_MARKERS_GLYPH_ID, CameraAlertChip, DEFAULT_GLYPHS_URL, DEFAULT_TERRAIN_ATTRIBUTION, DEFAULT_TERRAIN_URL, DEFAULT_TERRITORY_TILES_URL, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, GuidanceBanner, IsochroneLayer, LOGO_SVG, LogoControl, MARKERS_ID, MARKER_DEFAULT_COLOUR, MARKER_GLYPH_IDS, MARKER_GLYPH_VIEWBOX, MARKER_LABEL_TEXT_SIZES, MARKER_PIN_BODY_PATH, MARKER_SIZES, MARKER_SIZES_PX, MAX_MARKER_ID_LENGTH, MAX_MARKER_IMAGE_BYTES, MAX_MARKER_ITEMS, MAX_MARKER_LABEL_LENGTH, MAX_MARKER_TEXT_LENGTH, MAX_PUCK_IMAGE_BYTES, MapMapMap, MarkersLayer, NAV_ALERT_AUDIO_MODES, NAV_ALERT_CHIP_POSITIONS, NAV_ALERT_ICON_SETS, NAV_ALERT_LEAD_DISTANCES, NAV_ALERT_LEAD_DISTANCE_M, NAV_ALERT_MODES, NAV_ALERT_SOUNDS, NAV_ALERT_SOUND_BASE_URL, NAV_ALERT_SOUND_FILES, NAV_CAMERA_DEFAULTS, NAV_CAMERA_KINDS, NavigationCamera, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, PlacesLayer, PositionPuck, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, RouteLayer, SIGNAL_BLUE, SOURCE_LAYERS, ThemeScheduler, VoiceGuidance, alertChipContent, alertContrastIssues, alertIconSvg, alertIconUrl, alertPresentation, alertSoundUrl, alertSpeedReadoutColor, applyPoiDesign, applyTerrain, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, cameraKindLabel, cameraKindsShownOnMap, cameraShownOnMap, cameraSpriteName, cameraSymbolLayer, contrastRatio, createMap, createRouteEffect, defaultNavAlertsDesign, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, hasBakedMarkers, haversineDistanceM, isMarkerGlyphId, isNameTextField, laneArrowDirection, languageTextField, lngLatToMercator, markerGlyphPaths, markerImage, markerImageDataKey, markerImageKey, markerText, markerTextImageKey, markersFromTheme, markersFromThemeUrl, navAlertLeadDistanceM, navAlertSoundUrl, navCameraKind, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseHexColor, parseMarkers, parseNavAlertsDesign, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, relativeLuminance, removeTerrain, renderMarkerImage, resetDiagnostics, resolveTerrain, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, truncateChars, uploadProbeBatch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map