@trackunit/react-map-adapter-mapbox 0.0.149 → 0.0.152

package/index.cjs.js

@@ -2,6 +2,7 @@
 
 var reactMapAdapterShared = require('@trackunit/react-map-adapter-shared');
 var geoJsonUtils = require('@trackunit/geo-json-utils');
+var reactMapDraw = require('@trackunit/react-map-draw');
 var esToolkit = require('es-toolkit');
 var mapboxgl = require('mapbox-gl');
 var Supercluster = require('supercluster');
@@ -27,6 +28,27 @@ const MAPBOX_MAP_TYPE_STYLES = {
         dark: "mapbox://styles/mapbox/satellite-streets-v12",
     },
 };
+/**
+ * Style every Mapbox map is created with. The renderer passes it to `mapboxgl.Map`
+ * and the adapter instance records it as the applied style, so the two agree on
+ * what is on the map before the first `applyStyle`.
+ */
+const getInitialStyleUrl = (theme) => MAPBOX_MAP_TYPE_STYLES.roadmap[theme];
+
+/**
+ * Builds the Mapbox GL bridge for the shared drawing engine (ADR 0030).
+ *
+ * One loader per loaded style: `setStyle` (theme, map type, Roads) removes every
+ * custom source and layer, so `MapboxAdapterInstance` disconnects the controller
+ * before a style change and reconnects it with a fresh loader on `style.load`.
+ * Terra Draw and its Mapbox adapter are only downloaded when the loader runs.
+ */
+const createMapboxDrawEngineLoader = (map) => async () => {
+    const { TerraDrawMapboxGLAdapter } = await import('terra-draw-mapbox-gl-adapter');
+    return reactMapDraw.loadTerraDrawEngine({
+        adapter: new TerraDrawMapboxGLAdapter({ map, coordinatePrecision: reactMapDraw.DRAW_COORDINATE_PRECISION }),
+    });
+};
 
 // ============================================================================
 // Helpers
@@ -2440,15 +2462,29 @@ class MapboxAdapterInstance {
             initializationFailed: reactMapAdapterShared.INITIAL_MAP_STATE.initializationFailed,
             appearance: reactMapAdapterShared.INITIAL_MAP_STATE.appearance,
             tileSize: MAPBOX_TILE_SIZE,
+            drawing: reactMapAdapterShared.INITIAL_MAP_STATE.drawing,
         };
         this.cameraListeners = new Set();
         this.statusListeners = new Set();
         this.eventListeners = new Map();
         this.mapboxEventCleanups = [];
         this.isDestroyedFlag = false;
+        /**
+         * The map whose style has loaded at least once. `map.isStyleLoaded()` is false
+         * inside `style.load` and transiently while sources load, so the drawing bridge
+         * keeps its own readiness (same reason as `MapboxLayerPort.styleReady`).
+         */
+        this.styleLoadedMap = null;
+        /** Style URL currently applied to the map, so a same-URL change is skipped instead of reloaded. */
+        this.appliedStyleUrl = null;
         this.appearance = { ...reactMapAdapterShared.DEFAULT_MAP_APPEARANCE, theme: config.theme ?? "light" };
         this.layers = new MapboxLayerPort();
         this.layers.setTheme(this.appearance.theme);
+        // Engine load failures are not surfaced here (same as the deck.gl runtime): the
+        // controller keeps mode and value and loads again on the next connect, setMode
+        // or setValue that needs an engine.
+        this.draw = new reactMapDraw.DrawController();
+        this.draw.subscribe(() => this.syncDrawingStatus());
         this.state = { ...reactMapAdapterShared.computeInitialState(this.appearance, config.initialViewport), tileSize: MAPBOX_TILE_SIZE };
         this.cachedCameraState = {
             center: this.state.center,
@@ -2461,6 +2497,7 @@ class MapboxAdapterInstance {
             initializationFailed: this.state.initializationFailed,
             appearance: this.state.appearance,
             tileSize: this.state.tileSize,
+            drawing: this.state.drawing,
         };
     }
     // ============================================================================
@@ -2483,8 +2520,18 @@ class MapboxAdapterInstance {
         this.setupEventListeners();
         // Connect the layer port so it can render on this map
         this.layers.connect(map);
+        // Drawing lives in style-bound sources and layers, so the engine is (re)built on
+        // every style load and torn down before setStyle (ADR 0030). Mode and value survive
+        // in the controller; the engine is rebuilt from the committed value.
+        const connectDraw = () => this.connectDraw(map);
+        map.on("style.load", connectDraw);
+        this.mapboxEventCleanups.push(() => map.off("style.load", connectDraw));
+        if (this.styleLoadedMap === map || map.isStyleLoaded()) {
+            connectDraw();
+        }
+        this.appliedStyleUrl = getInitialStyleUrl(this.appearance.theme);
         // Set isReady and notify status listeners before syncing camera state
-        this.state = { ...this.state, isReady: true, initializationFailed: false };
+        this.state = { ...this.state, isReady: true, initializationFailed: false, drawing: this.draw.getMode() !== "idle" };
         this.updateStatusCache();
         this.notifyStatusListeners();
         // Sync initial map state
@@ -2603,12 +2650,7 @@ class MapboxAdapterInstance {
         const currentMap = this.map;
         if (currentMap === null)
             return;
-        const effectiveType = this.effectiveMapType();
-        const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
-        return new Promise(resolve => {
-            currentMap.setStyle(styleUrl);
-            currentMap.once("idle", () => resolve());
-        });
+        return this.applyStyle(currentMap);
     }
     async setTheme(theme) {
         if (this.appearance.theme === theme)
@@ -2621,12 +2663,7 @@ class MapboxAdapterInstance {
         const currentMap = this.map;
         if (currentMap === null)
             return;
-        const effectiveType = this.effectiveMapType();
-        const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
-        return new Promise(resolve => {
-            currentMap.setStyle(styleUrl);
-            currentMap.once("idle", () => resolve());
-        });
+        return this.applyStyle(currentMap);
     }
     async setShowRoads(showRoads) {
         if (this.appearance.showRoads === showRoads)
@@ -2640,12 +2677,7 @@ class MapboxAdapterInstance {
         if (currentMap === null)
             return;
         if (this.appearance.mapType === "satellite" || this.appearance.mapType === "hybrid") {
-            const effectiveType = this.effectiveMapType();
-            const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
-            return new Promise(resolve => {
-                currentMap.setStyle(styleUrl);
-                currentMap.once("idle", () => resolve());
-            });
+            return this.applyStyle(currentMap);
         }
     }
     on(event, handler) {
@@ -2679,7 +2711,8 @@ class MapboxAdapterInstance {
     }
     destroy() {
         this.isDestroyedFlag = true;
-        // Clean up layer port before removing event listeners
+        // Clean up drawing and layer port before removing event listeners
+        this.draw.disconnect();
         this.layers.destroy();
         // Remove all Mapbox event listeners
         this.mapboxEventCleanups.forEach(cleanup => cleanup());
@@ -2807,6 +2840,39 @@ class MapboxAdapterInstance {
         this.updateCameraCache();
         this.notifyCameraListeners();
     }
+    connectDraw(map) {
+        this.styleLoadedMap = map;
+        this.draw.connect(createMapboxDrawEngineLoader(map));
+    }
+    /**
+     * Applies the style for the current appearance.
+     *
+     * Satellite light and dark share one URL, and satellite with roads is the hybrid
+     * URL, so a change can resolve to the style already on the map. Mapbox diffs such
+     * a request as a no-op and never fires `style.load`; skipping it keeps the layers
+     * and the drawing in place. For a real change the drawing is torn down first and
+     * rebound on `style.load`, with `idle` as the safety net should the load event not
+     * fire.
+     */
+    applyStyle(currentMap) {
+        const styleUrl = MAPBOX_MAP_TYPE_STYLES[this.effectiveMapType()][this.appearance.theme];
+        if (styleUrl === this.appliedStyleUrl)
+            return Promise.resolve();
+        this.appliedStyleUrl = styleUrl;
+        return new Promise(resolve => {
+            this.draw.disconnect();
+            currentMap.setStyle(styleUrl);
+            currentMap.once("idle", () => {
+                // A late idle after destroy() or after a map swap must not attach Terra Draw
+                // to a torn-down adapter or a dead map.
+                const stillCurrent = this.map === currentMap && !this.isDestroyedFlag;
+                if (stillCurrent && !this.draw.isConnected()) {
+                    this.connectDraw(currentMap);
+                }
+                resolve();
+            });
+        });
+    }
     /**
      * Resolves the effective Mapbox style key: when the user asks for "satellite"
      * with roads enabled, we use "hybrid" (satellite + road labels).
@@ -2822,8 +2888,17 @@ class MapboxAdapterInstance {
         this.cachedCameraState = { center, zoom, bounds, isIdle };
     }
     updateStatusCache() {
-        const { isReady, initializationFailed, appearance, tileSize } = this.state;
-        this.cachedStatus = { isReady, initializationFailed, appearance, tileSize };
+        const { isReady, initializationFailed, appearance, tileSize, drawing } = this.state;
+        this.cachedStatus = { isReady, initializationFailed, appearance, tileSize, drawing };
+    }
+    /** Mirrors the draw controller's mode into `MapStatus.drawing` (ADR 0030). */
+    syncDrawingStatus() {
+        const drawing = this.draw.getMode() !== "idle";
+        if (this.state.drawing === drawing)
+            return;
+        this.state = { ...this.state, drawing };
+        this.updateStatusCache();
+        this.notifyStatusListeners();
     }
     notifyCameraListeners() {
         this.cameraListeners.forEach(listener => listener());
@@ -2912,7 +2987,7 @@ const MapboxMapInternal = ({ adapterInstance, children, className, style, theme,
             const mapOptions = initialViewport?.type === "bounds"
                 ? {
                     container: el,
-                    style: MAPBOX_MAP_TYPE_STYLES.roadmap[theme],
+                    style: getInitialStyleUrl(theme),
                     bounds: bboxToLngLatBounds(initialViewport.bounds),
                     fitBoundsOptions: initialViewport.padding !== undefined || initialViewport.maxZoom !== undefined
                         ? {
@@ -2925,7 +3000,7 @@ const MapboxMapInternal = ({ adapterInstance, children, className, style, theme,
                 }
                 : {
                     container: el,
-                    style: MAPBOX_MAP_TYPE_STYLES.roadmap[theme],
+                    style: getInitialStyleUrl(theme),
                     center: initialViewport?.type === "center"
                         ? { lng: initialViewport.center[0], lat: initialViewport.center[1] }
                         : { lng: reactMapAdapterShared.DEFAULT_CENTER.lng, lat: reactMapAdapterShared.DEFAULT_CENTER.lat },

package/index.esm.js

@@ -1,6 +1,7 @@
 import { canPatchAdaptiveMarker, canPatchAdaptiveViewport, canPatchMarkerInPlace, getAdaptiveDomFeatureIds, buildAdaptiveSymbolStyleFn, extractPointCoordinates, resolveCircleSymbolDefaults, resolveSymbolDescriptor, mergeAntimeridianFeatures, densifyGeodesicFeatures, LAYER_FADE_DURATION_MS, patchPortalDescriptors, buildAdaptiveDomRenderFn, extractSourceData, collectFeatureIdSet, removeGoneIndexedMarkers, createSymbolDotElement, createDefaultClusterElement, createClusterPinElement, fadeInElement, buildAdaptiveDomEntries, attachSafeAreaHoverListeners, resolveSelectedStyle, resolveHoveredStyle, MAP_CURSORS, geometryTypeToShapeType, INITIAL_MAP_STATE, DEFAULT_MAP_APPEARANCE, computeInitialState, cameraStateEquals, isEventOfType, getEffectiveRestrictBounds, DEFAULT_ZOOM, DEFAULT_CENTER, defineAdapter } from '@trackunit/react-map-adapter-shared';
 export { mapboxMapCspDirectives } from '@trackunit/react-map-adapter-shared';
 import { validateBbox, validatePosition } from '@trackunit/geo-json-utils';
+import { loadTerraDrawEngine, DRAW_COORDINATE_PRECISION, DrawController } from '@trackunit/react-map-draw';
 import { isEqual } from 'es-toolkit';
 import mapboxgl from 'mapbox-gl';
 import Supercluster from 'supercluster';
@@ -26,6 +27,27 @@ const MAPBOX_MAP_TYPE_STYLES = {
         dark: "mapbox://styles/mapbox/satellite-streets-v12",
     },
 };
+/**
+ * Style every Mapbox map is created with. The renderer passes it to `mapboxgl.Map`
+ * and the adapter instance records it as the applied style, so the two agree on
+ * what is on the map before the first `applyStyle`.
+ */
+const getInitialStyleUrl = (theme) => MAPBOX_MAP_TYPE_STYLES.roadmap[theme];
+
+/**
+ * Builds the Mapbox GL bridge for the shared drawing engine (ADR 0030).
+ *
+ * One loader per loaded style: `setStyle` (theme, map type, Roads) removes every
+ * custom source and layer, so `MapboxAdapterInstance` disconnects the controller
+ * before a style change and reconnects it with a fresh loader on `style.load`.
+ * Terra Draw and its Mapbox adapter are only downloaded when the loader runs.
+ */
+const createMapboxDrawEngineLoader = (map) => async () => {
+    const { TerraDrawMapboxGLAdapter } = await import('terra-draw-mapbox-gl-adapter');
+    return loadTerraDrawEngine({
+        adapter: new TerraDrawMapboxGLAdapter({ map, coordinatePrecision: DRAW_COORDINATE_PRECISION }),
+    });
+};
 
 // ============================================================================
 // Helpers
@@ -2439,15 +2461,29 @@ class MapboxAdapterInstance {
             initializationFailed: INITIAL_MAP_STATE.initializationFailed,
             appearance: INITIAL_MAP_STATE.appearance,
             tileSize: MAPBOX_TILE_SIZE,
+            drawing: INITIAL_MAP_STATE.drawing,
         };
         this.cameraListeners = new Set();
         this.statusListeners = new Set();
         this.eventListeners = new Map();
         this.mapboxEventCleanups = [];
         this.isDestroyedFlag = false;
+        /**
+         * The map whose style has loaded at least once. `map.isStyleLoaded()` is false
+         * inside `style.load` and transiently while sources load, so the drawing bridge
+         * keeps its own readiness (same reason as `MapboxLayerPort.styleReady`).
+         */
+        this.styleLoadedMap = null;
+        /** Style URL currently applied to the map, so a same-URL change is skipped instead of reloaded. */
+        this.appliedStyleUrl = null;
         this.appearance = { ...DEFAULT_MAP_APPEARANCE, theme: config.theme ?? "light" };
         this.layers = new MapboxLayerPort();
         this.layers.setTheme(this.appearance.theme);
+        // Engine load failures are not surfaced here (same as the deck.gl runtime): the
+        // controller keeps mode and value and loads again on the next connect, setMode
+        // or setValue that needs an engine.
+        this.draw = new DrawController();
+        this.draw.subscribe(() => this.syncDrawingStatus());
         this.state = { ...computeInitialState(this.appearance, config.initialViewport), tileSize: MAPBOX_TILE_SIZE };
         this.cachedCameraState = {
             center: this.state.center,
@@ -2460,6 +2496,7 @@ class MapboxAdapterInstance {
             initializationFailed: this.state.initializationFailed,
             appearance: this.state.appearance,
             tileSize: this.state.tileSize,
+            drawing: this.state.drawing,
         };
     }
     // ============================================================================
@@ -2482,8 +2519,18 @@ class MapboxAdapterInstance {
         this.setupEventListeners();
         // Connect the layer port so it can render on this map
         this.layers.connect(map);
+        // Drawing lives in style-bound sources and layers, so the engine is (re)built on
+        // every style load and torn down before setStyle (ADR 0030). Mode and value survive
+        // in the controller; the engine is rebuilt from the committed value.
+        const connectDraw = () => this.connectDraw(map);
+        map.on("style.load", connectDraw);
+        this.mapboxEventCleanups.push(() => map.off("style.load", connectDraw));
+        if (this.styleLoadedMap === map || map.isStyleLoaded()) {
+            connectDraw();
+        }
+        this.appliedStyleUrl = getInitialStyleUrl(this.appearance.theme);
         // Set isReady and notify status listeners before syncing camera state
-        this.state = { ...this.state, isReady: true, initializationFailed: false };
+        this.state = { ...this.state, isReady: true, initializationFailed: false, drawing: this.draw.getMode() !== "idle" };
         this.updateStatusCache();
         this.notifyStatusListeners();
         // Sync initial map state
@@ -2602,12 +2649,7 @@ class MapboxAdapterInstance {
         const currentMap = this.map;
         if (currentMap === null)
             return;
-        const effectiveType = this.effectiveMapType();
-        const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
-        return new Promise(resolve => {
-            currentMap.setStyle(styleUrl);
-            currentMap.once("idle", () => resolve());
-        });
+        return this.applyStyle(currentMap);
     }
     async setTheme(theme) {
         if (this.appearance.theme === theme)
@@ -2620,12 +2662,7 @@ class MapboxAdapterInstance {
         const currentMap = this.map;
         if (currentMap === null)
             return;
-        const effectiveType = this.effectiveMapType();
-        const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
-        return new Promise(resolve => {
-            currentMap.setStyle(styleUrl);
-            currentMap.once("idle", () => resolve());
-        });
+        return this.applyStyle(currentMap);
     }
     async setShowRoads(showRoads) {
         if (this.appearance.showRoads === showRoads)
@@ -2639,12 +2676,7 @@ class MapboxAdapterInstance {
         if (currentMap === null)
             return;
         if (this.appearance.mapType === "satellite" || this.appearance.mapType === "hybrid") {
-            const effectiveType = this.effectiveMapType();
-            const styleUrl = MAPBOX_MAP_TYPE_STYLES[effectiveType][this.appearance.theme];
-            return new Promise(resolve => {
-                currentMap.setStyle(styleUrl);
-                currentMap.once("idle", () => resolve());
-            });
+            return this.applyStyle(currentMap);
         }
     }
     on(event, handler) {
@@ -2678,7 +2710,8 @@ class MapboxAdapterInstance {
     }
     destroy() {
         this.isDestroyedFlag = true;
-        // Clean up layer port before removing event listeners
+        // Clean up drawing and layer port before removing event listeners
+        this.draw.disconnect();
         this.layers.destroy();
         // Remove all Mapbox event listeners
         this.mapboxEventCleanups.forEach(cleanup => cleanup());
@@ -2806,6 +2839,39 @@ class MapboxAdapterInstance {
         this.updateCameraCache();
         this.notifyCameraListeners();
     }
+    connectDraw(map) {
+        this.styleLoadedMap = map;
+        this.draw.connect(createMapboxDrawEngineLoader(map));
+    }
+    /**
+     * Applies the style for the current appearance.
+     *
+     * Satellite light and dark share one URL, and satellite with roads is the hybrid
+     * URL, so a change can resolve to the style already on the map. Mapbox diffs such
+     * a request as a no-op and never fires `style.load`; skipping it keeps the layers
+     * and the drawing in place. For a real change the drawing is torn down first and
+     * rebound on `style.load`, with `idle` as the safety net should the load event not
+     * fire.
+     */
+    applyStyle(currentMap) {
+        const styleUrl = MAPBOX_MAP_TYPE_STYLES[this.effectiveMapType()][this.appearance.theme];
+        if (styleUrl === this.appliedStyleUrl)
+            return Promise.resolve();
+        this.appliedStyleUrl = styleUrl;
+        return new Promise(resolve => {
+            this.draw.disconnect();
+            currentMap.setStyle(styleUrl);
+            currentMap.once("idle", () => {
+                // A late idle after destroy() or after a map swap must not attach Terra Draw
+                // to a torn-down adapter or a dead map.
+                const stillCurrent = this.map === currentMap && !this.isDestroyedFlag;
+                if (stillCurrent && !this.draw.isConnected()) {
+                    this.connectDraw(currentMap);
+                }
+                resolve();
+            });
+        });
+    }
     /**
      * Resolves the effective Mapbox style key: when the user asks for "satellite"
      * with roads enabled, we use "hybrid" (satellite + road labels).
@@ -2821,8 +2887,17 @@ class MapboxAdapterInstance {
         this.cachedCameraState = { center, zoom, bounds, isIdle };
     }
     updateStatusCache() {
-        const { isReady, initializationFailed, appearance, tileSize } = this.state;
-        this.cachedStatus = { isReady, initializationFailed, appearance, tileSize };
+        const { isReady, initializationFailed, appearance, tileSize, drawing } = this.state;
+        this.cachedStatus = { isReady, initializationFailed, appearance, tileSize, drawing };
+    }
+    /** Mirrors the draw controller's mode into `MapStatus.drawing` (ADR 0030). */
+    syncDrawingStatus() {
+        const drawing = this.draw.getMode() !== "idle";
+        if (this.state.drawing === drawing)
+            return;
+        this.state = { ...this.state, drawing };
+        this.updateStatusCache();
+        this.notifyStatusListeners();
     }
     notifyCameraListeners() {
         this.cameraListeners.forEach(listener => listener());
@@ -2911,7 +2986,7 @@ const MapboxMapInternal = ({ adapterInstance, children, className, style, theme,
             const mapOptions = initialViewport?.type === "bounds"
                 ? {
                     container: el,
-                    style: MAPBOX_MAP_TYPE_STYLES.roadmap[theme],
+                    style: getInitialStyleUrl(theme),
                     bounds: bboxToLngLatBounds(initialViewport.bounds),
                     fitBoundsOptions: initialViewport.padding !== undefined || initialViewport.maxZoom !== undefined
                         ? {
@@ -2924,7 +2999,7 @@ const MapboxMapInternal = ({ adapterInstance, children, className, style, theme,
                 }
                 : {
                     container: el,
-                    style: MAPBOX_MAP_TYPE_STYLES.roadmap[theme],
+                    style: getInitialStyleUrl(theme),
                     center: initialViewport?.type === "center"
                         ? { lng: initialViewport.center[0], lat: initialViewport.center[1] }
                         : { lng: DEFAULT_CENTER.lng, lat: DEFAULT_CENTER.lat },

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@trackunit/react-map-adapter-mapbox",
-  "version": "0.0.149",
+  "version": "0.0.152",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-map-adapter-shared": "0.0.161",
-    "@trackunit/geo-json-utils": "1.18.9",
+    "@trackunit/react-map-adapter-shared": "0.0.164",
+    "@trackunit/geo-json-utils": "1.19.0",
     "mapbox-gl": "^3.18.1",
     "supercluster": "^8.0.1",
     "es-toolkit": "^1.52.0",
     "react-device-detect": "^2.2.3",
-    "zod": "^3.25.76"
+    "zod": "^3.25.76",
+    "@trackunit/react-map-draw": "0.0.2",
+    "terra-draw-mapbox-gl-adapter": "^1.4.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/MapboxAdapterInstance.d.ts

@@ -1,4 +1,5 @@
 import { type AdapterInstance, type BaseAdapterConfig, type CameraState, type FitBoundsOptions, type GeoJsonBbox, type GeoJsonPosition, type MapEvent, type MapEventHandler, type MapStatus, type MapTheme, type MapType } from "@trackunit/react-map-adapter-shared";
+import { DrawController } from "@trackunit/react-map-draw";
 import { MapboxLayerPort } from "./MapboxLayerPort";
 /**
  * Configuration for Mapbox adapter
@@ -15,6 +16,11 @@ export declare class MapboxAdapterInstance implements AdapterInstance<MapboxConf
     private readonly config;
     /** Layer rendering port -- manages markers, shapes, routes, and overlays on the map */
     readonly layers: MapboxLayerPort;
+    /**
+     * Drawing capability (ADR 0030). The controller keeps mode and value across style
+     * reloads; `connect()` rebinds it on every `style.load`.
+     */
+    readonly draw: DrawController;
     private map;
     private state;
     private cachedCameraState;
@@ -24,6 +30,14 @@ export declare class MapboxAdapterInstance implements AdapterInstance<MapboxConf
     private readonly eventListeners;
     private mapboxEventCleanups;
     private isDestroyedFlag;
+    /**
+     * The map whose style has loaded at least once. `map.isStyleLoaded()` is false
+     * inside `style.load` and transiently while sources load, so the drawing bridge
+     * keeps its own readiness (same reason as `MapboxLayerPort.styleReady`).
+     */
+    private styleLoadedMap;
+    /** Style URL currently applied to the map, so a same-URL change is skipped instead of reloaded. */
+    private appliedStyleUrl;
     /** Unified appearance state — theme, mapType, and showRoads in one place */
     private appearance;
     constructor(config: MapboxConfig);
@@ -61,6 +75,18 @@ export declare class MapboxAdapterInstance implements AdapterInstance<MapboxConf
      * Used by movestart (false) and the idle path already calls updateState (true).
      */
     private setIdleState;
+    private connectDraw;
+    /**
+     * Applies the style for the current appearance.
+     *
+     * Satellite light and dark share one URL, and satellite with roads is the hybrid
+     * URL, so a change can resolve to the style already on the map. Mapbox diffs such
+     * a request as a no-op and never fires `style.load`; skipping it keeps the layers
+     * and the drawing in place. For a real change the drawing is torn down first and
+     * rebound on `style.load`, with `idle` as the safety net should the load event not
+     * fire.
+     */
+    private applyStyle;
     /**
      * Resolves the effective Mapbox style key: when the user asks for "satellite"
      * with roads enabled, we use "hybrid" (satellite + road labels).
@@ -68,6 +94,8 @@ export declare class MapboxAdapterInstance implements AdapterInstance<MapboxConf
     private effectiveMapType;
     private updateCameraCache;
     private updateStatusCache;
+    /** Mirrors the draw controller's mode into `MapStatus.drawing` (ADR 0030). */
+    private syncDrawingStatus;
     private notifyCameraListeners;
     private notifyStatusListeners;
     private emitEvent;

package/src/constants.d.ts

@@ -1,3 +1,4 @@
+import type { MapTheme } from "@trackunit/react-map-adapter-shared";
 /**
  * Mapbox style URLs for different map types
  */
@@ -15,3 +16,9 @@ export declare const MAPBOX_MAP_TYPE_STYLES: {
         readonly dark: "mapbox://styles/mapbox/satellite-streets-v12";
     };
 };
+/**
+ * Style every Mapbox map is created with. The renderer passes it to `mapboxgl.Map`
+ * and the adapter instance records it as the applied style, so the two agree on
+ * what is on the map before the first `applyStyle`.
+ */
+export declare const getInitialStyleUrl: (theme: MapTheme) => string;

package/src/draw/createMapboxDrawEngineLoader.d.ts

@@ -0,0 +1,10 @@
+import { type DrawEngineLoader } from "@trackunit/react-map-draw";
+/**
+ * Builds the Mapbox GL bridge for the shared drawing engine (ADR 0030).
+ *
+ * One loader per loaded style: `setStyle` (theme, map type, Roads) removes every
+ * custom source and layer, so `MapboxAdapterInstance` disconnects the controller
+ * before a style change and reconnects it with a fresh loader on `style.load`.
+ * Terra Draw and its Mapbox adapter are only downloaded when the loader runs.
+ */
+export declare const createMapboxDrawEngineLoader: (map: mapboxgl.Map) => DrawEngineLoader;