Document that map:ready fires before the base map style loads

docs/api.md

@@ -1056,7 +1056,9 @@ interactiveMap.on('app:continue', ({ pluginStates, mapState }) => {
 
 ### `map:ready`
 
-Emitted when the underlying map is ready and initial app state (style and size) has settled.
+Emitted when the underlying map instance has been created and initial app state (style and size) has settled. The map is created once the layout and safe zone have been calculated, and uses the safe zone as its initial padding.
+
+The base map may still be loading when `map:ready` fires. Wait for [`map:loaded`](#maploaded) before adding sources or layers to the underlying map.
 
 **Payload:**
 
@@ -1076,6 +1078,20 @@ interactiveMap.on('map:ready', ({ map, mapStyleId, mapSize }) => {
 
 ---
 
+### `map:loaded`
+
+Emitted once, when the initial base map has loaded. Emitted after `map:ready`. Sources and layers can be added to the underlying map from this point.
+
+**Payload:** None on MapLibre and OpenLayers. ESRI passes the current map state (`center`, `bounds`, `resolution`, `zoom`, `isAtMaxZoom`, `isAtMinZoom`).
+
+```js
+interactiveMap.on('map:loaded', () => {
+  console.log('Base map loaded')
+})
+```
+
+---
+
 ### `map:stylechange`
 
 Emitted when the map style finishes loading after a style change.

docs/api/context.md

@@ -96,6 +96,8 @@ Current map state, including:
 }
 ```
 
+`mapState.isMapReady` is `true` once the map instance has been created (`map:ready`). The base map may still be loading at that point; check `mapProvider.isBaseMapReady()` before adding sources or layers to the underlying map.
+
 ---
 
 ### `services`

src/config/events.js

@@ -178,11 +178,13 @@ export const EVENTS = {
    */
   MAP_STYLE_CHANGE: 'map:stylechange',
 
-  /** Emitted when the map has fully loaded. */
+  /** Emitted once, when the initial base map has loaded. */
   MAP_LOADED: 'map:loaded',
 
   /**
-   * Emitted when the map is ready for interaction and initial app state is settled.
+   * Emitted when the map instance has been created and initial app state (style and size) is settled.
+   * The base map may still be loading; wait for `MAP_LOADED` before adding sources or layers
+   * to the underlying map.
    *
    * Payload:
    * - `map` — the underlying map instance