diff --git a/docs/api.md b/docs/api.md
index 56f6fa1f..c422448d 100644
--- a/docs/api.md
+++ b/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.
diff --git a/docs/api/context.md b/docs/api/context.md
index dd658438..b2495345 100644
--- a/docs/api/context.md
+++ b/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`
diff --git a/src/config/events.js b/src/config/events.js
index bcbf511c..81ebbc0f 100644
--- a/src/config/events.js
+++ b/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