@maptiler/sdk 4.2.0-rc.1 → 5.0.0-beta.m-r.1

package/dist/Map.d.ts

@@ -1,4 +1,4 @@
-import { default as maplibregl, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification, FlyToOptions, EaseToOptions, FitBoundsOptions, AnimationOptions, LngLatBoundsLike, LngLatLike } from 'maplibre-gl';
+import { Map as MapMLGL, StyleSpecification, MapOptions as MapOptionsML, ControlPosition, StyleSwapOptions, StyleOptions, RequestTransformFunction, LayerSpecification, SourceSpecification, CustomLayerInterface, FilterSpecification, StyleSetterOptions, ProjectionSpecification, FlyToOptions, EaseToOptions, FitBoundsOptions, AnimationOptions, LngLatBoundsLike, LngLatLike, AllPaintProperties, AllLayoutProperties, MapEventType, MapLayerEventType, Listener, Subscription, TerrainSpecification, Event as EventML } from 'maplibre-gl';
 import { ReferenceMapStyle, MapStyleVariant } from '@maptiler/client';
 import { SdkConfig } from './config';
 import { LanguageInfo } from './language';
@@ -8,6 +8,7 @@ import { Telemetry } from './Telemetry';
 import { CubemapDefinition, CubemapLayer, CubemapLayerConstructorOptions } from './custom-layers/CubemapLayer';
 import { GradientDefinition, RadialGradientLayer, RadialGradientLayerConstructorOptions } from './custom-layers/RadialGradientLayer';
 import { StyleSpecificationWithMetaData } from './custom-layers/extractCustomLayerStyle';
+import { MapTilerMarkerOptions, Marker, MarkerCollisionOptions, RemoveMarkerOptions } from '.';
 export type LoadWithTerrainEvent = {
     type: "loadWithTerrain";
     target: Map;
@@ -16,6 +17,45 @@ export type LoadWithTerrainEvent = {
         exaggeration: number;
     };
 };
+/**
+ * Shape of an event fired by the SDK on top of the MapLibre events,
+ * with the properties passed to `fire(type, properties)` merged in.
+ */
+type SDKMapEvent<TType extends string, TProps extends object = object> = EventML<TType> & {
+    target: Map;
+} & TProps;
+/**
+ * Events fired by the MapTiler SDK `Map` in addition to the MapLibre ones.
+ */
+export type MaptilerMapEventType = {
+    /** Fired once the map style and the SDK controls are ready */
+    ready: SDKMapEvent<"ready">;
+    /** Fired once the map is loaded and the terrain (if any) is ready */
+    loadWithTerrain: LoadWithTerrainEvent;
+    /** Fired when the WebGL context is lost unexpectedly (i.e. not after `map.remove()`) */
+    webglContextLost: SDKMapEvent<"webglContextLost">;
+    terrainAnimationStart: SDKMapEvent<"terrainAnimationStart", {
+        terrain: TerrainSpecification | null;
+    }>;
+    terrainAnimationStop: SDKMapEvent<"terrainAnimationStop", {
+        terrain: TerrainSpecification | null;
+    }>;
+    "projection.change": SDKMapEvent<"projection.change", {
+        projection: ProjectionSpecification;
+    }>;
+    "cubemaplayer:animateindone": SDKMapEvent<"cubemaplayer:animateindone", Partial<CubemapLayer>>;
+    "cubemaplayer:animateoutdone": SDKMapEvent<"cubemaplayer:animateoutdone", Partial<CubemapLayer>>;
+    "cubemaplayer:onremove": SDKMapEvent<"cubemaplayer:onremove", Partial<CubemapLayer>>;
+    "radialgradientlayer:animateindone": SDKMapEvent<"radialgradientlayer:animateindone", Partial<RadialGradientLayer>>;
+    "radialgradientlayer:animateoutdone": SDKMapEvent<"radialgradientlayer:animateoutdone", Partial<RadialGradientLayer>>;
+    "radialgradientlayer:onremove": SDKMapEvent<"radialgradientlayer:onremove", Partial<RadialGradientLayer>>;
+};
+/**
+ * All the events that can be listened to on a MapTiler SDK `Map`: the MapLibre ones plus the SDK ones.
+ * Since MapLibre v6.3, `on`/`once`/`off`/`fire` only accept the keys of `MapEventType`,
+ * so the SDK `Map` overrides them to accept its own events as well.
+ */
+export type MapEventTypeSDK = MapEventType & MaptilerMapEventType;
 export declare const GeolocationType: {
     POINT: "POINT";
     COUNTRY: "COUNTRY";
@@ -25,6 +65,11 @@ export declare const GeolocationType: {
  * if falls back to the default Mercator
  */
 export type ProjectionTypes = "mercator" | "globe" | undefined;
+/**
+ * Default zoom at/above which a `"globe"` projection request switches to flat mercator — see
+ * {@link MapOptions.globeMercatorSwitchZoom}.
+ */
+export declare const DEFAULT_GLOBE_MERCATOR_SWITCH_ZOOM = 11;
 /**
  * The {@link AttributionControl} options object
  */
@@ -157,6 +202,26 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo" | "attribut
      * If not provided, the style takes precedence. If provided, overwrite the style.
      */
     projection?: ProjectionTypes;
+    /**
+     * MapLibre's plain `type: "globe"` already resolves to
+     * `["interpolate", ["linear"], ["zoom"], 11, "vertical-perspective", 12, "mercator"]` —
+     * vertical-perspective below zoom 11, linearly blended into flat mercator between 11 and 12.
+     * That blend is a MapLibre bug for anything that places objects via its per-projection model
+     * matrix (marker altitude, `maptiler-3d-js`): the matrix isn't well-defined mid-blend, only
+     * once it's settled fully at one end, so objects placed while zooming through 11-12 jump
+     * around.
+     *
+     * Whenever a projection change resolves to `"globe"` (constructor option, `setProjection`, or
+     * the {@link MaptilerProjectionControl}), the SDK requests
+     * `{ type: ["step", ["zoom"], "vertical-perspective", globeMercatorSwitchZoom, "mercator"] }`
+     * instead of the literal string — spherical below this zoom, flat mercator at and above it,
+     * snapping instantly at the threshold instead of blending across that zoom band.
+     *
+     * Set to `false` to request MapLibre's own `"globe"` literally instead, blend bug and all.
+     *
+     * Default: `11`
+     */
+    globeMercatorSwitchZoom?: number | false;
     /**
      * Turn on/off spacebox.
      *
@@ -169,11 +234,6 @@ export type MapOptions = Omit<MapOptionsML, "style" | "maplibreLogo" | "attribut
      * Default: Unless this is set explicitly to false, the SDK version will be logged to the console.
      */
     logSDKVersion?: boolean;
-    /**
-     * Whether to enable the RTL plugin or import a different one.
-     * Default is undefined, which means the plugin is enabled by default.
-     */
-    rtlTextPlugin?: boolean | string;
     /**
      * Whether to enable the experimental tile preloading feature.
      * Default is false.
@@ -202,8 +262,36 @@ export interface ProjectionChangeOptions {
 /**
  * The Map class can be instanciated to display a map in a `<div>`
  */
-export declare class Map extends maplibregl.Map {
+export declare class Map extends MapMLGL {
     readonly telemetry: Telemetry;
+    /**
+     * Adds a listener for events of a specified type, optionally limited to features in one or more layers.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    on<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): Subscription;
+    on<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): Subscription;
+    on(type: keyof MapEventTypeSDK, listener: Listener): Subscription;
+    /**
+     * Adds a listener that will be called only once to a specified event type, optionally limited to features in one or more layers.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): this;
+    once<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[]): Promise<MapLayerEventType[T] & object>;
+    once<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): this;
+    once<T extends keyof MapEventTypeSDK>(type: T): Promise<MapEventTypeSDK[T] & object>;
+    once(type: keyof MapEventTypeSDK, listener?: Listener): this | Promise<any>;
+    /**
+     * Removes an event listener previously added with {@link Map.on} or {@link Map.once}.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    off<T extends keyof MapLayerEventType>(type: T, layerIds: string | string[], listener: (ev: MapLayerEventType[T] & object) => void): this;
+    off<T extends keyof MapEventTypeSDK>(type: T, listener: (ev: MapEventTypeSDK[T] & object) => void): this;
+    off(type: keyof MapEventTypeSDK, listener: Listener): this;
+    /**
+     * Fires an event. Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMapEventType}).
+     */
+    fire(event: MapEventTypeSDK[keyof MapEventTypeSDK]): this;
+    fire(type: keyof MapEventTypeSDK, properties?: object): this;
     private space?;
     private halo?;
     getSpace(): CubemapLayer | undefined;
@@ -261,6 +349,7 @@ export declare class Map extends maplibregl.Map {
     private terrainAnimationDuration;
     private monitoredStyleUrls;
     private styleInProcess;
+    private currentStyleId?;
     private curentProjection;
     private originalLabelStyle;
     private isStyleLocalized;
@@ -310,6 +399,13 @@ export declare class Map extends maplibregl.Map {
      */
     setStyle(style: null | ReferenceMapStyle | MapStyleVariant | StyleSpecification | StyleSpecificationWithMetaData | string, options?: StyleSwapOptions & StyleOptions): this;
     private spaceboxLoadingState;
+    /**
+     * Returns the id of the current MapTiler style (e.g. `"streets-v4-dark"`),
+     * derived from the value passed to the constructor or `setStyle`.
+     * `undefined` when the style is a custom `StyleSpecification` or a URL that
+     * doesn't follow the MapTiler Cloud `/maps/<id>/style.json` shape.
+     */
+    getStyleId(): string | undefined;
     /**
      * Adds a [MapLibre style layer](https://maplibre.org/maplibre-style-spec/layers)
      * to the map's style.
@@ -361,6 +457,49 @@ export declare class Map extends maplibregl.Map {
      * ```
      */
     removeLayer(id: string): this;
+    /**
+     * Adds a marker to the map, registering it for collision handling and style-aware colours.
+     * Plays the marker's `enter` animation, if it has one.
+     * @param markerOrMarkerConfig - A `Marker`, or the options to create one from.
+     */
+    addMarker(markerOrMarkerConfig: Marker | MapTilerMarkerOptions): this;
+    /**
+     * Removes a marker from the map, playing its `exit` animation first, if it has one.
+     * @param id - Id of the marker to remove.
+     * @param options.immediate - Removes the marker straight away, without its `exit` animation.
+     */
+    removeMarker(id: string, options?: RemoveMarkerOptions): this;
+    /**
+     * Adds several markers to the map. See {@link Map.addMarker}.
+     * @param markers - `Marker`s, or the options to create them from.
+     */
+    addMarkers(markers: (Marker | MapTilerMarkerOptions)[]): this;
+    /**
+     * Removes several markers from the map, playing their `exit` animations first, if they have them.
+     * @param markerIds - Ids of the markers to remove. Removes every marker when omitted.
+     * @param options.immediate - Removes the markers straight away, without their `exit` animations.
+     */
+    removeMarkers(markerIds?: string[], options?: RemoveMarkerOptions): this;
+    /** Returns every marker added to the map. */
+    getMarkers(): Marker[];
+    /** Returns the marker with the given id, or `undefined` if it isn't on the map. */
+    getMarker(id: string): Marker | undefined;
+    /**
+     * Configures marker collision detection for this map.
+     * @param options.proximityPadding - Distance in CSS px within which two
+     *   markers count as "in proximity". Overlap always uses 0.
+     * @param options.accuracy - `high` (default) tests rotated markers with
+     *   their actual rotated box; `low` uses the upright box enclosing it,
+     *   which is cheaper per pair but over-reports collisions for rotated
+     *   markers (it never misses a real one).
+     * @param options.behaviour - Default collision behaviour applied to every
+     *   marker on this map (`always-show` | `hide-by-priority` |
+     *   `minimize-by-priority`). A marker's own `collisionBehaviour` option
+     *   overrides it. Defaults to `always-show`.
+     * @param options.transitionDuration - Duration in ms of the hide/show/minimize fade. Defaults to `150`.
+     * @param options.transitionEasing - CSS easing function for the fade. Defaults to `"ease"`.
+     */
+    setMarkerCollisionOptions(options: MarkerCollisionOptions): this;
     /**
      * Sets the zoom extent for the specified style layer. The zoom extent includes the
      * [minimum zoom level](https://maplibre.org/maplibre-style-spec/layers/#minzoom)
@@ -399,7 +538,7 @@ export declare class Map extends maplibregl.Map {
      * map.setPaintProperty('my-layer', 'fill-color', '#faafee');
      * ```
      */
-    setPaintProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setPaintProperty<K extends keyof AllPaintProperties>(layerId: string, name: K, value: AllPaintProperties[K], options?: StyleSetterOptions): this;
     /**
      * Sets the value of a layout property in the specified style layer.
      * Layout properties define how the layer is styled.
@@ -413,7 +552,7 @@ export declare class Map extends maplibregl.Map {
      * @param options - Options object.
      * @returns `this`
      */
-    setLayoutProperty(layerId: string, name: string, value: any, options?: StyleSetterOptions): this;
+    setLayoutProperty<K extends keyof AllLayoutProperties>(layerId: string, name: K, value: AllLayoutProperties[K], options?: StyleSetterOptions): this;
     /**
      * Sets the value of the style's glyphs property.
      *
@@ -509,7 +648,11 @@ export declare class Map extends maplibregl.Map {
      */
     getProjection(): ProjectionSpecification;
     /**
-     * Returns whether a globe projection is currently being used
+     * Returns whether a globe-family projection is currently configured — `"globe"`,
+     * `"vertical-perspective"`, or the `globeMercatorSwitchZoom` step expression this class
+     * requests for `"globe"` (see {@link MapOptions.globeMercatorSwitchZoom}). This reflects the
+     * configured projection, not the instantaneous rendered state — under the step expression it
+     * stays `true` even after zooming past the switch threshold into flat mercator rendering.
      */
     isGlobeProjection(): boolean;
     /**
@@ -530,7 +673,7 @@ export declare class Map extends maplibregl.Map {
      * Sets the projection to a {@linkcode ProjectionSpecification}.
      * @param projection - the projection specification to set
      */
-    setProjection(projection: maplibregl.ProjectionSpecification): this;
+    setProjection(projection: ProjectionSpecification): this;
     /**
      * Forget the persisted projection - from both constructor option and result of any `map.setProjection(..., { persist: true })` calls.
      */
@@ -684,3 +827,4 @@ export declare class Map extends maplibregl.Map {
      */
     private resolveCameraPosition;
 }
+export {};

package/dist/Marker/Marker.d.ts

@@ -0,0 +1,397 @@
+import { Marker as MLMarker, CustomLayerProjectionData, LngLatLike, PointLike, Subscription } from 'maplibre-gl';
+import { Map as SDKMap } from '../Map';
+import { MapTilerMarkerElementOptions, MapTilerMarkerSVGOptions, PendingMarkerUpdates, Vector2, MapTilerMarkerOptions, MarkerCollisionEventData, MarkerCollisionDisplayState, MapTilerMarkerUIStateName, UIStateSpec, MarkerTransitionProperty, MapTilerMarkerTransitions, MarkerTransitionSpec, MarkerEventTypeSDK, GroundLineOptions, AltitudeReference, SetAltitudeOptions } from './types';
+import { MarkerFootprint } from './collision-helpers';
+import { PendingUpdatesSymbol, DetachFromDOMSymbol, FlushDOMUpdatesSymbol, MarkerElementSymbol, RefreshAdaptiveColorSymbol, CollisionFootprintSymbol, EmitCollisionDiffSymbol, ApplyCollisionDisplayStateSymbol, ApplyAltitudeFrameSymbol, MeasuredElementSizeSymbol, ClearFocusStateSymbol, AttachToMapSymbol } from './marker-symbols';
+/** MapLibre's `Marker` extended with 2-D scale, named shapes, colour tokens, and batched DOM updates. */
+export declare class Marker extends MLMarker {
+    /** Construction-time options snapshot — not updated by setters. */
+    readonly options: MapTilerMarkerOptions;
+    readonly _scale = 1;
+    /** Current values of all element-affecting properties. Written only via {@link setProp}. */
+    private readonly props;
+    /** Whether the shape anchor offset is auto-managed — `false` with an explicit `offset` or custom `element`. */
+    private readonly managesOffset;
+    /** The DOM element **/
+    [MarkerElementSymbol]: HTMLElement;
+    /** Property updates waiting to be flushed to the DOM on the next animation frame. */
+    [PendingUpdatesSymbol]: PendingMarkerUpdates;
+    /** Unscaled CSS pixel size of a custom `element`, measured once at registration. `null` until measured; unused for built-in SVG markers. */
+    [MeasuredElementSizeSymbol]: Vector2 | null;
+    /** UUID that uniquely identifies this marker instance. */
+    readonly id: string;
+    /**
+     * The `classList` of the marker's wrapper element — the inner transform
+     * wrapper of a built-in marker, or the custom `element` itself. Read-only
+     * reference; add and remove classes through the returned list.
+     */
+    get classList(): DOMTokenList;
+    /** How the collision engine is currently displaying this marker. */
+    private collisionDisplayState;
+    /** Visual props overridden while minimized, restored from {@link props} on un-minimize. Empty when not minimized. */
+    private minimizedKeys;
+    /** Whether the minimized appearance is currently applied to the DOM. Lags {@link collisionDisplayState} during fades. */
+    private minimizedApplied;
+    /** Pending mid-fade appearance swap for minimize transitions. */
+    private minimizeSwapTimer;
+    /** Pending post-fade cull (`display: none`) while hidden. */
+    private cullTimer;
+    /** Pending release of the collision fade class once no fade/dip is in flight. */
+    private fadeClassReleaseTimer;
+    /** Registered property overrides per UI state, keyed by state name. */
+    private uiStates;
+    /** UI states currently active (interaction-driven). */
+    private readonly activeUIStates;
+    /** Keys owned by the flattened active UI state, masked out of DOM flushes like {@link minimizedKeys}. */
+    private appliedUIStateKeys;
+    /** Registered per-property transition config, keyed by property name. */
+    private transitions;
+    /** In-flight transitions, keyed by property — at most one each. `"opacity"` isn't a public {@link MarkerTransitionProperty}, reused for enter/exit fades. */
+    private readonly activeTransitions;
+    /** The currently-looping `idle` animation, if any — started after `enter` finishes (or immediately), stopped on `remove()`. */
+    private idleAnimation;
+    /** Configured enter/idle/exit lifecycle animations. */
+    private animations;
+    /** Set during `addTo()`'s call into the base `addTo()`, which calls `this.remove()` first to detach from any previous map. */
+    private suppressLifecycleAnimations;
+    /** Altitude in meters, faked via a per-frame pixel offset (MapLibre's Marker has no native Z). 0 by default — see {@link setAltitude}. */
+    private altitudeMeters;
+    /** What {@link altitudeMeters} is measured from — see {@link AltitudeReference}. */
+    private altitudeReference;
+    /** True once {@link setAltitude} has been called at least once — see {@link hasActiveAltitude}. */
+    private altitudeEngaged;
+    /** The offset MapLibre would show with no altitude applied. Only {@link writeOffset} should write the real offset — anything that calls `super.setOffset` directly clobbers altitude. */
+    private baseOffset;
+    /** Pixel delta from `groundBase` to `elevated`, added to {@link baseOffset}. Null when off-screen/behind camera. */
+    private altitudeDelta;
+    /** The `elevated` point in absolute canvas CSS pixels — the ground line's position. */
+    private groundLineOrigin;
+    /** True when off-screen/behind the camera. Not the below-ground case — see {@link altitudeOccluded}. */
+    private altitudeHidden;
+    /** True when below ground (`computeAltitudeProjection`'s `belowGround`). */
+    private altitudeOccluded;
+    private groundLineEnabled;
+    private groundLineOptions;
+    private groundLineEl;
+    /**
+     * Creates a marker from a pre-built DOM or SVG element.
+     *
+     * `shape`/`size` don't apply. Color/shadow options still apply as CSS
+     * custom properties for the element's own styles to consume.
+     */
+    constructor(options: MapTilerMarkerElementOptions);
+    /** Creates a marker styled via the built-in SVG system (`shape`, `size`, colour tokens, shadow). With no options, uses the default appearance. */
+    constructor(options?: MapTilerMarkerSVGOptions);
+    /**
+     * Adds a listener for events of a specified type.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMarkerEventType}).
+     */
+    on<T extends keyof MarkerEventTypeSDK>(type: T, listener: (ev: MarkerEventTypeSDK[T]) => void): Subscription;
+    /**
+     * Adds a listener that will be called only once to a specified event type.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMarkerEventType}).
+     */
+    once<T extends keyof MarkerEventTypeSDK>(type: T): Promise<MarkerEventTypeSDK[T]>;
+    once<T extends keyof MarkerEventTypeSDK>(type: T, listener: (ev: MarkerEventTypeSDK[T]) => void): this;
+    /**
+     * Removes an event listener previously added with {@link Marker.on} or {@link Marker.once}.
+     * Accepts the MapLibre events as well as the SDK events (see {@link MaptilerMarkerEventType}).
+     */
+    off<T extends keyof MarkerEventTypeSDK>(type: T, listener: (ev: MarkerEventTypeSDK[T]) => void): this;
+    /**
+     * Adds the marker to a map. Equivalent to `map.addMarker(marker)`, which it delegates to.
+     * @deprecated Use `map.addMarker(marker)` instead. Kept for MapLibre-style call sites and will be removed in a future major version.
+     * @param map - Target map instance.
+     */
+    addTo(map: SDKMap): this;
+    /**
+     * Attaches the marker to a map, and plays the configured `enter` animation (if any) once attached.
+     * Called only by `MarkerManager` during registration.
+     * @param map - Target map instance.
+     */
+    [AttachToMapSymbol](map: SDKMap): this;
+    /** Recomputes the shape anchor offset so the shape's tip stays on the lngLat. No-op with an explicit `offset` or custom `element`. */
+    private applyShapeAnchorOffset;
+    /**
+     * Records a property's new value and schedules a DOM flush on the next
+     * animation frame via {@link MarkerManager}.
+     * @param prop - The element property to update.
+     * @param value - The new value for the property.
+     */
+    private setProp;
+    /**
+     * Applies all pending property updates to the marker element and clears
+     * the batch. Called by {@link MarkerManager} on the next animation frame.
+     */
+    [FlushDOMUpdatesSymbol](): void;
+    /** Returns the style id of the map this marker is on, or `undefined` when detached. */
+    private getCurrentStyleId;
+    /** Queues re-resolving every unset colour against the current map style. */
+    [RefreshAdaptiveColorSymbol](): void;
+    /** Sets one colour prop; `undefined` returns it to its map-style default (resolved at flush time, so nothing to transition to). */
+    private setColorProp;
+    /** A colour prop's value in effect — the explicit one, else the default for the map's style. */
+    private getEffectiveColor;
+    /** Resolves the marker's screen footprint for collision detection. Always full-size, even minimized. */
+    [CollisionFootprintSymbol](): MarkerFootprint;
+    /** Shape/size keys, or minimized substitutes. */
+    private effectiveShapeAndSize;
+    /** Screen offset for the collision footprint. */
+    private footprintOffset;
+    /** Fires the collision transition event (`markeroverlap`/`markerproximity`). */
+    [EmitCollisionDiffSymbol](data: MarkerCollisionEventData): void;
+    /**
+     * Applies the collision engine's display-state decision.
+     *
+     * Every transition fades. Hide/show fade in place; visible<->minimized
+     * fades *through* zero (dip out, swap at the invisible midpoint, fade back in).
+     */
+    [ApplyCollisionDisplayStateSymbol](state: MarkerCollisionDisplayState): void;
+    /** Toggles the collision-hidden fade and reschedules releasing the fade class — see {@link fadeClassReleaseTimer}. */
+    private setCollisionHidden;
+    /** The fade duration (ms) configured for this marker's map, or the SDK default when off a map. */
+    private collisionTransitionMs;
+    /** Applies or restores the minimized appearance if it differs from what the DOM shows. */
+    private setMinimizedApplied;
+    /** Returns how the collision engine is currently displaying this marker. */
+    getCollisionDisplayState(): MarkerCollisionDisplayState;
+    /** The visual props the minimized appearance overrides for this marker. */
+    private minimizedOverrides;
+    /** Applies or restores the minimized appearance, straight to the DOM (never {@link setProp}). */
+    private applyMinimizedAppearance;
+    /** Builds the batch restoring `keys` to their prop values. */
+    private restoreUpdates;
+    /**
+     * Sets the marker's geographical position.
+     * @param lnglat - The new position.
+     */
+    setLngLat(lnglat: LngLatLike): this;
+    /**
+     * Sets the marker's screen-space pixel offset. Composes with altitude (see {@link writeOffset}) rather than replacing it.
+     * @param offset - Offset in pixels (+y down).
+     */
+    setOffset(offset: PointLike): this;
+    /** The only path that should write MapLibre's real offset: records `offset` as {@link baseOffset}, then writes `base + altitudeDelta`. Callers must never use `super.setOffset` directly, or altitude gets silently dropped. */
+    private writeOffset;
+    /**
+     * Sets the 2-D scale of the marker as `[x, y]`.
+     * @param scaleVector - Scale factors for the x and y axes.
+     */
+    setScale(scaleVector: Vector2): void;
+    /** Returns the current 2-D scale. Defaults to `[1, 1]`. */
+    getScale(): Vector2 | undefined;
+    /**
+     * Sets the marker shape. Applies the new anchor offset (see {@link applyShapeAnchorOffset}).
+     * @param shape - Marker shape key.
+     */
+    setShape(shape: MapTilerMarkerOptions["shape"]): void;
+    /** Returns the current shape, or `undefined` if never set. */
+    getShape(): import('./types').MapTilerMarkerShape | undefined;
+    /**
+     * Sets the marker size.
+     * @param size - Marker size key.
+     */
+    setSize(size: MapTilerMarkerOptions["size"]): void;
+    /** Returns the current size, or `undefined` if never explicitly set. */
+    getSize(): import('./types').MapTilerMarkerSize | undefined;
+    /**
+     * Sets the drop-shadow intensity.
+     * @param shadow - Shadow intensity preset, or `undefined` to reset to the default (`"medium"`). Use `"none"` to disable.
+     */
+    setShadow(shadow: MapTilerMarkerOptions["shadow"]): void;
+    /** Returns the current shadow preset, or `undefined` if none is set. */
+    getShadow(): import('./types').MapTilerMarkerShadow | undefined;
+    /**
+     * Sets the fill colour of the outer body of the marker.
+     * @param color - Any valid CSS colour string, or `undefined` to return to the map-style default.
+     */
+    setOuterColor(color: MapTilerMarkerOptions["outerColor"]): void;
+    /** Returns the outer body colour currently in effect — the explicit `outerColor`, else the default for the map's style. */
+    getOuterColor(): string;
+    /**
+     * Sets an explicit fill colour for the inner area of the marker, replacing
+     * the map-style default.
+     * @param color - Any valid CSS colour string, or `undefined` to return to the map-style default.
+     */
+    setInnerColor(color: MapTilerMarkerOptions["innerColor"]): void;
+    /** Returns the inner area colour currently in effect — the explicit `innerColor`, else the default for the map's style. */
+    getInnerColor(): string;
+    /**
+     * Sets the colour applied to the marker content (icon, text, etc.).
+     * @param color - Any valid CSS colour string, or `undefined` to return to the map-style default.
+     */
+    setContentColor(color: MapTilerMarkerOptions["contentColor"]): void;
+    /** Returns the content colour currently in effect — the explicit `contentColor`, else the default for the map's style. */
+    getContentColor(): string;
+    /**
+     * Sets the stroke colour of the marker outline.
+     * Has no visible effect unless {@link setOutline} is also called.
+     * @param color - Any valid CSS colour string, or `undefined` to return to the map-style default.
+     */
+    setOutlineColor(color: MapTilerMarkerOptions["outlineColor"]): void;
+    /** Returns the outline stroke colour currently in effect — the explicit `outlineColor`, else the default for the map's style. */
+    getOutlineColor(): string;
+    /**
+     * Sets the outline stroke width on the marker body.
+     * @param outline - `true` for the default width, a positive `number` for an
+     *   explicit pixel width, or `undefined` to remove the outline.
+     */
+    setOutline(outline: MapTilerMarkerOptions["outline"]): void;
+    /** Returns the current outline value (`true`, a pixel width, or `undefined`). */
+    getOutline(): number | true | undefined;
+    /**
+     * Sets the `title` attribute on the marker's root element (native tooltip).
+     * @param title - Tooltip string, or `undefined` to remove the attribute.
+     */
+    setTitle(title: MapTilerMarkerOptions["title"]): void;
+    /** Returns the current title string. */
+    getTitle(): string | undefined;
+    /**
+     * Sets the text content displayed inside the marker body.
+     * @param content - Label string, or `undefined` to clear.
+     */
+    setContent(content: MapTilerMarkerOptions["content"]): void;
+    /** Returns the current content string. */
+    getContent(): string | undefined;
+    /**
+     * Sets the rendering priority.
+     * @param priority - Numeric priority, a MapLibre-style expression, or
+     *   `undefined` to restore DOM-order stacking.
+     */
+    setPriority(priority: MapTilerMarkerOptions["priority"]): void;
+    /** Returns the current rendering priority, or `undefined` if never set. */
+    getPriority(): number | import('./types').MarkerPriorityExpression | undefined;
+    /**
+     * Shows or hides the debug overlay, which renders the marker's bounding
+     * box and center point on top of the marker element.
+     * @param debug - `true` to show the overlay, `false`/`undefined` to hide it.
+     */
+    setDebug(debug: MapTilerMarkerOptions["debug"]): void;
+    /** Returns whether the debug overlay is currently enabled. */
+    getDebug(): boolean;
+    /**
+     * Rotates the marker's inner shell element in degrees, via the CSS
+     * `scale(x, y) rotate(deg)` transform on the inner wrapper — independent
+     * of MapLibre's own rotation on the outer container.
+     * @param rotation - Clockwise rotation in degrees.
+     */
+    setRotation(rotation: number): this;
+    /**
+     * Returns the current inner-shell rotation in degrees.
+     * @returns Rotation in degrees; `0` if never set.
+     */
+    getRotation(): number;
+    private attachUIStateListeners;
+    /** Blurs the marker's focusable element. Called by {@link MarkerManager} on map `click`. */
+    [ClearFocusStateSymbol](): void;
+    private setUIStateActive;
+    private applyUIStates;
+    /**
+     * Registers (or replaces) the property overrides applied while `name` is
+     * active. Applies immediately if that state is currently active.
+     * @param name - UI state to configure.
+     * @param spec - Property overrides to apply while the state is active.
+     */
+    setUIState(name: MapTilerMarkerUIStateName, spec: UIStateSpec): void;
+    /**
+     * Configures (or clears) the easing used the next time `property` changes.
+     * @param property - Transitionable property to configure.
+     * @param transition - `[duration, easing?, delay?]` in milliseconds, or `null` to make future changes snap immediately again.
+     */
+    setTransitionForProperty(property: MarkerTransitionProperty, transition: MarkerTransitionSpec | null): void;
+    /** Returns a copy of the currently configured per-property transitions. */
+    getTransitions(): MapTilerMarkerTransitions;
+    /**
+     * Applies `to` to `property`, either immediately or by easing from `from`
+     * when a transition is configured. Fires `transitionstart`/`transitionend`.
+     * @param property - Transitionable property being changed.
+     * @param from - Current value.
+     * @param to - Value being set.
+     * @param codec - Bridges `T` to/from the flat numeric props the underlying animation interpolates.
+     * @param apply - Writes an interpolated (or the immediate) value to the marker.
+     */
+    private applyTransitionable;
+    /** Cancels any transition in flight for `property`, leaving its current (mid-transition) value as-is. */
+    private cancelTransition;
+    /** Cancels every transition in flight. Called on removal so a destroyed marker's props can't keep animating. */
+    private cancelAllTransitions;
+    /** Runs `preset`'s enter/exit motion (opacity + scale + lift) from `from` to `to`. */
+    private playLifecycleTransition;
+    /** Runs a `custom` enter/exit animation: an eased `0`→`1` alpha handed to `spec.custom` every frame. */
+    private playCustomLifecycleAnimation;
+    /** Clears the enter-mask opacity set at construction. Idempotent, safe to call unconditionally — each enter/exit path (preset or `custom`) is responsible for calling it on its own first frame, since the SDK can't know in advance whether a `custom` callback touches opacity. */
+    private clearEnterMask;
+    /** Plays the configured `enter` animation, easing from {@link enterPresetHiddenValue} up to the marker's own configured state. */
+    private playEnterAnimation;
+    /** Plays the configured `exit` animation, easing from the marker's own configured state down to {@link exitPresetHiddenValue}. */
+    private playExitAnimation;
+    /** Wires play/iteration/stop bookkeeping around a `value`-keyframed animation, and plays it. */
+    private runIdleAnimation;
+    /** Starts the configured `idle` loop — `preset`'s single channel (see {@link IDLE_PRESET_CONFIG}), or a `custom` callback fed a `0`→`1` alpha. */
+    private startIdleAnimation;
+    /** Stops the currently-looping `idle` animation, if any, leaving the marker at its current (mid-loop) state. */
+    private stopIdleAnimation;
+    /**
+     * Sets altitude in meters above the ground plane (negative is fine — below
+     * ground/sea level), faked via a per-frame pixel offset. `options.relativeTo`
+     * (default `"ground"`) picks what the meters are measured from. There is
+     * deliberately no fast path for `meters: 0`: MapLibre's native marker
+     * position is already terrain-elevated whenever the map has terrain, so
+     * doing nothing at `0` would leave the marker on the terrain, not at
+     * ground/sea level.
+     *
+     * Pass `false` to unset: deregisters and clamps to MapLibre's own native
+     * (terrain-aware) position, same as a marker that never called this.
+     * @param meters - Altitude in meters, measured per `options.relativeTo`, or `false` to unset altitude entirely.
+     * @param options - See {@link SetAltitudeOptions}. Ignored when `meters` is `false`.
+     * @experimental
+     */
+    setAltitude(meters: false): this;
+    setAltitude(meters: number, options?: SetAltitudeOptions): this;
+    /**
+     * Returns the current altitude in meters, or 0 if never set.
+     * @experimental
+     */
+    getAltitude(): number;
+    /**
+     * Returns what {@link getAltitude}'s meters are measured from. Defaults to `"ground"`.
+     * @experimental
+     */
+    getAltitudeReference(): AltitudeReference;
+    /**
+     * True from the first {@link setAltitude} call onward.
+     * @experimental
+     */
+    hasActiveAltitude(): boolean;
+    /** Stamps `altitude`/`altitudeReference`/`altitudeEngaged` onto every `dragstart`/`drag`/`dragend` event. */
+    fire(event: string | {
+        type: string;
+    }, properties?: Record<string, unknown>): this;
+    /**
+     * Toggles a dashed line from the marker down (or up) to its ground point.
+     * Off by default. See `.maptiler-marker-groundline` in
+     * the SDK stylesheet and {@link GroundLineOptions.className}.
+     * @param enabled - Whether to show the line.
+     * @param options - Optional extra CSS class for styling.
+     * @experimental
+     */
+    setGroundLine(enabled: boolean, options?: GroundLineOptions): this;
+    /**
+     * Per-frame altitude hook, called by {@link MarkerManager} for every altitude-active marker. Returns the elevated point's camera depth (used to rank z-index among altitude-active markers), or `null` when off-screen/behind the camera.
+     */
+    [ApplyAltitudeFrameSymbol](projectionData: CustomLayerProjectionData, map: SDKMap): number | null;
+    /** Idempotent toggle for {@link altitudeHidden} — cheap to call every frame regardless of whether the state actually changed. */
+    private setAltitudeHidden;
+    /** Idempotent toggle for {@link altitudeOccluded} — cheap to call every frame regardless of whether the state actually changed. */
+    private setAltitudeOccluded;
+    /**
+     * Creates/updates/removes the ground-line element. Geometry (position/width/rotation) comes from {@link altitudeDelta}/{@link groundLineOrigin}. Lives in a shared container at the map level ({@link MarkerManager.getGroundLineContainer}), not nested in this marker's own element — otherwise a long line would inherit its marker's camera-depth z-index and could paint over another marker's icon.
+     */
+    private updateGroundLineElement;
+    /** Removes the marker from the DOM directly, bypassing {@link MarkerManager}. */
+    [DetachFromDOMSymbol](): void;
+    /** Removes the marker, playing the configured `exit` animation first (if any) before detaching from the DOM. */
+    remove(): this;
+    /** Deregisters (if registered) and detaches from the DOM immediately — no exit animation. */
+    private detachImmediately;
+}